NextGIS Frontend
    Preparing search index...

    NextGIS Frontend

    NextGIS Frontend

    Github lerna version

    NextGIS Code

    A suite of frontend JavaScript libraries designed to accelerate the development of web-GIS applications using NextGIS software and services as a backend. NextGIS Frontend supports three major open-source GIS frameworks with unified interfaces.

    Most applications should use one of the ready-to-use map packages:

    Package Rendering engine
    @nextgis/ngw-leaflet Leaflet
    @nextgis/ngw-ol OpenLayers
    @nextgis/ngw-maplibre-gl MapLibre GL JS

    All three provide the common NgwMap API. Use @nextgis/ngw-connector for NextGIS Web HTTP API requests without a map, and @nextgis/ngw-kit for NextGIS Web map adapters and resource utilities.

    React applications can use the matching react-ngw-* component. Applications that already have a native Leaflet, OpenLayers, or MapLibre GL JS map can use the matching qms-* package to add services from NextGIS QMS.

    See the package architecture and selection guide for the relationship between public packages, ngw-map, webmap, and map adapters.

    Single-file bundles for rapid deployment of web-gis applications with NextGIS services. These packages bundle a mapping library with NextGIS integration, allowing you to quickly create a web map with minimal setup:

    Building blocks for custom Web GIS frontends and map libraries:

    Map-free libraries to interaction with NextGIS Web. These packages allow you to work with NextGIS Web backend capabilities without needing a map component:

    These libraries provide React components to easily embed NextGIS Web maps into React applications. Each package targets a specific mapping library:

    Use an engine-specific package with an existing native map. Use qms-core without a map, or qms-kit when building on the common webmap API:

    • qms-leaflet – QMS layers and search control for Leaflet;
    • qms-ol – QMS layers and search control for OpenLayers;
    • qms-maplibre-gl – QMS layers and search control for MapLibre GL JS;
    • qms-core – map-independent QMS client, catalog, and shared control UI;
    • qms-kit – QMS layer adapter for webmap-based libraries.

    General-purpose utilities that are not tied to any mapping framework. These support libraries provide common functionality useful across NextGIS Frontend projects:

    • utils – common development tools;
    • cache - caching for asynchronous functions;
    • cancelable-promise – a promise you can stop;
    • dom – collection of libraries for working with the DOM;

    Download and include with a <script> tag. The [package] will be registered as a global variable.

    <script src="./lib/[package].global.js"></script>
    <script>
      const package = new Package(options);
    </script>

    You can also load the ES module build directly in a modern browser:

    <script type="module">
      import Package from 'https://unpkg.com/@nextgis/[package]/lib/[package].esm-browser.prod.js';
    </script>

    Choose between unpkg and jsdelivr as a CDN to include a package without downloading:

    Using unpkg:

    <script src="https://unpkg.com/@nextgis/[package]"></script>
    <script src="https://unpkg.com/@nextgis/[package]@[version]"></script>
    <script src="https://unpkg.com/@nextgis/[package]@[version]/lib/[file]"></script>

    Using jsdelivr

    <script src="https://cdn.jsdelivr.net/npm/@nextgis/[package]"></script>
    <script src="https://cdn.jsdelivr.net/npm/@nextgis/[package]@[version]/lib/[file]"></script>

    [file] represents the specific bundle file - [package].[format].prod.js

    [format] can be:

    • global - browser script
    • cjs - node module
    • esm-browser - browser module
    • esm-bundler - module for bundler systems

    NOTE! It is highly recommended to pin to a specific [version] number that you can update manually for stability

    Install the desired package via npm:

    npm install @nextgis/[package]

    Then import and use the [package] in your project code:

    // Import the package (default export or named exports as needed)
    import Package from '@nextgis/[package]';
    // import { Component, utilityFn } from '@nextgis/[package]';

    // Initialize and use the package
    const package = new Package(options);

    Below is a basic example using the ready-to-use Leaflet package. Replace the import with @nextgis/ngw-ol or @nextgis/ngw-maplibre-gl to use another rendering engine with the same common API:

    import NgwMap from '@nextgis/ngw-leaflet';

    const ngwMap = new NgwMap({
      target: 'map', // ID of the HTML element for the map
      qmsId: 448, // Optional QMS basemap ID (from NextGIS QMS)
      baseUrl: 'https://demo.nextgis.com', // Base URL of your NextGIS Web instance
      resources: [
        2011, // add a NextGIS Web resource by numeric ID
        { resource: 222, fit: true }, // add resource 222 and zoom ("fit") to it
        { resource: 'keyname' }, // add a resource by its keyname (alias)
      ],
    });

    ngwMap.onLoad().then(() => {
      // This callback runs when the map and all layers have finished loading
      console.log('Map is ready!');
    });

    You can easily add layers from NextGIS Web to an existing map. The NgwMap.addNgwLayer method accepts a resource ID or keyname from your NextGIS Web and optional parameters:

    // Add a layer by numeric resource ID:
    ngwMap.addNgwLayer({ resource: 2011 });

    // Add a layer by resource keyname:
    ngwMap.addNgwLayer({ resource: 'keyname' });

    // Add a vector layer from a NextGIS Web *style* resource (by keyname):
    ngwMap.addNgwLayer({ resource: 'vector_style_keyname', adapter: 'GEOJSON' });

    // Add the first style of a vector resource (if available) as a tiled layer:
    ngwMap.addNgwLayer({ resource: 'vector_layer_keyname', adapter: 'TILE' });

    The resource field can be either an ID or a keyname (string) of the layer/webmap in NextGIS Web. For a more in-depth example, see the Add different NextGIS Web resource demo which shows various ways to add resources.

    If you plan to use NextGIS Frontend libraries in a TypeScript project, we recommend installing the NextGIS Web type declarations. NextGIS provides a CLI tool @nextgis/ngw-types-loader to download TypeScript definitions for your NextGIS Web instance and configure your project automatically

    Run the loader to install declarations generated by NextGIS Web:

    npx @nextgis/ngw-types-loader

    By default, it fetches declarations from demo.nextgis.com. The generated modules are installed under node_modules/@nextgisweb and resolve without changes to tsconfig.json.

    If you are using a self-hosted NextGIS Web instance, specify its URL to get types specific to your deployment:

    npx @nextgis/ngw-types-loader https://your-custom-ngw-url.com

    For more details, refer to the NGW Types Loader.

    To work with the NextGIS Frontend monorepo locally, ensure you have Yarn installed. Then run:

    # Clone the repository
    git clone git@github.com:nextgis/nextgis_frontend.git
    cd nextgis_frontend

    # Install all dependencies
    yarn install

    # Build all packages (production builds)
    yarn run prod

    # Build the demo app (for local testing of examples)
    yarn run demo

    After building, you can run the local demo application to see examples of each library in action. You can also copy over the universal example pages into each package’s example directory by running:

    yarn run examples

    This will update example pages in the packages with the latest demo examples.

    Each package in the monorepo can be worked on and built individually. For example, to work on the webmap package:

    # Navigate to the package directory
    cd packages/webmap

    # Start a development build (with watch for changes)
    yarn run dev

    # (or) Build the package for production
    yarn run prod

    # You can also continuously watch source files for changes
    yarn run watch

    (For maintainers) Before publishing updates, run the release checks from the repository root:

    npm run prod
    npm test
    npm run test-build

    Then choose the command matching the release type. It updates the unified version of all packages and creates the release commit and tag:

    npm run patch
    npm run minor
    npm run major

    Review the generated commit and tag before pushing them. Publish the versioned packages to npm with:

    npm run publish:packages

    To publish a brand new package (if one is added to the monorepo) for the first time, go into that package folder and run:

    npm publish --access=public

    This repository includes a comprehensive test suite. Tests cover all packages and can be run from the root:

    npm t # run all test with coverage
    npm run karma # run karma test in watch mode for development

    Need to fix a bug or add a feature to NextGIS Frontend? We provide custom development and support for this software. Contact us to discuss options!

    http://nextgis.com

    Settings
    Member Visibility

    On This Page
    NextGIS Frontend