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.

    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:

    Bricks for build custom Web GIS frontend:

    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:

    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 of creating a map with NextGIS Frontend. This example uses NgwMap (which handles NextGIS Web integration) with a Leaflet map adapter:

    import { NgwMap } from '@nextgis/ngw-map';

    // Choose one of the map adapters:
    import 'leaflet/dist/leaflet.css';
    import MapAdapter from '@nextgis/leaflet-map-adapter';
    // OR, for OpenLayers:
    // import 'ol/ol.css';
    // import MapAdapter from '@nextgis/ol-map-adapter';
    // OR, for MapLibre GL:
    // import 'maplibre-gl/dist/maplibre-gl.css';
    // import MapAdapter from '@nextgis/maplibre-gl-map-adapter';

    const ngwMap = new NgwMap(new MapAdapter(), {
    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 following command to download the latest NextGIS Web TypeScript declaration file:

    npx @nextgis/ngw-types-loader
    

    By default, this will fetch type definitions from the public NextGIS Web demo at demo.nextgis.com and save them as a nextgisweb.d.ts file in your project. It will also prompt to update your tsconfig.json to include this definitions file

    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
    

    After running the tool, ensure that your tsconfig.json includes the downloaded file:

    {
    "include": [
    "./nextgisweb.d.ts"
    ]
    }

    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, make sure to build all packages in production mode:

    npm run prod
    

    To publish a new version of all packages to npm (and create a git tag), use Lerna from the root of the repository:

    npm run publish
    

    You will be prompted to choose the new version number, which will be applied to all packages (the monorepo uses a unified version). Lerna will handle inter-package dependencies during the version bump.

    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