NextGIS Frontend

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.

Table of Contents

• Quick Links
• Featured Examples
• Packages @nextgis/[package-name]
  • Ready-to-use maps
  • Map development tools
  • NextGIS Web (NGW) Tools
  • React integration components
  • Utilities
• Getting Started
  • Browser Integration
    • Include assets
    • Via CDN
  • Node.js Integration
• Usage
  • Map Creation
  • Adding Layers from NextGIS Web
• TypeScript Support
  • Installing NGW Types
• Developer Guide
  • Repository Setup
  • Package-Specific Instructions
  • Publishing
  • Testing
• Commercial Support

Quick Links

• Live Examples & Documentation
• API Documentation
• GitHub Repository
• Vue2 GitHub Repository
• Related Article
• Tutorial Repository
• NextGIS Official Website
• NextGIS Web
• Cloud Pricing Plans
• On-Premise Pricing
• Telegram Chat

Featured Examples

• Add layer from NextGIS Web
• Add webmap from NextGIS Web
• Zoom to NextGIS Web layer feature, partial data load
• Highlight features from NextGIS Web webmap
• Expression paint
• Layer properties filters
• BBOX strategy for vector layer
• Custom layers control
• Events
• Data management in the vector layer
• GeoJSON data
• Toggle button control
• Vector selection
• Vector popup
• Web map feature identification
• Web map bookmarks

Packages @nextgis/[package-name]

Ready-to-use maps

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:

• ngw-leaflet – for Leaflet;
• ngw-ol – for OpenLayers;
• ngw-maplibre-gl – for Maplibre GL JS;

Map development tools

Bricks for build custom Web GIS frontend:

• webmap – universal map constructor;
• leaflet-map-adapter – webmap adapter to use Leaflet GIS framework;
• maplibre-gl-map-adapter – webmap adapter to use Maplibre GL JS framework;
• ol-map-adapter – webmap adapter to use OpenLayers GIS framework;
• qms-kit – build webmap with NextGIS QMS baselayer;
• icons – simple svg icons pack to display on the map;
• dialog – utility to work with modal windows;
• control-container – placing control elements in the corners of the map container;
• paint – working with the style of vector layers;
• properties-filter – filtering objects by its properties using JSON-serializable expressions;
• url-runtime-params – writing and reading URL parameters;
• item – hierarchical layers control;
• geocoder - modern geocoder on async generators. May use different data providers.

NextGIS Web (NGW) Tools

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

• ngw-connector – module to interact with NextGIS Web REST API;
• ngw-kit – build webmap with NextGIS Web instance. Lots of useful utilities for interacting with the NextGIS Web API;
• ngw-orm – NextGIS Web Object-Relational Mapping;
• ngw-uploader – library providing tools for uploading data to nextgis.com cloud;
• ngw-map – abstract map to simplify work with NextGIS services;

React integration components

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

• react-ngw-map – base React component for NextGIS Web maps (works with Leaflet, OpenLayers, or MapLibre GL via adapters);
• react-ngw-leaflet – React NGW map component for Leaflet;
• react-ngw-ol – React NGW map component for OpenLayers;
• react-ngw-maplibre-gl – React NGW map component for Maplibre GL JS.

Utilities

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;

Getting Started

Browser Integration

Include assets

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>

Via CDN

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

Node.js Integration

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);

Usage

Map Creation

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!');
});

Adding Layers from NextGIS Web

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.

TypeScript Support

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

Installing NGW Types

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.

Developer Guide

Repository Setup

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

# Clone the repository
git clone [email protected]: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.

Package-Specific Instructions

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

Publishing

(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

Testing

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

Commercial support

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!