NextGIS Frontend
    Preparing search index...

    Package architecture

    NextGIS Frontend is a monorepo of composable mapping libraries. Most applications should start with one of the ready-to-use NextGIS Web map packages. Lower-level packages are available for applications that need to assemble or extend the map stack themselves.

    Package Use it when
    @nextgis/ngw-leaflet You need a ready-to-use NextGIS Web map based on Leaflet.
    @nextgis/ngw-ol You need a ready-to-use NextGIS Web map based on OpenLayers.
    @nextgis/ngw-maplibre-gl You need a ready-to-use NextGIS Web map based on MapLibre GL JS.
    @nextgis/ngw-kit You need NextGIS Web layer adapters, identification helpers, feature requests, legends, or other map-related utilities.
    @nextgis/ngw-connector You need to call the NextGIS Web HTTP API without creating a map.
    @nextgis/ngw-types-loader You need TypeScript declarations generated by a particular NextGIS Web deployment.

    The three ngw-* map packages expose the same common map API. Choose between them according to the rendering engine and its ecosystem. They configure the corresponding map adapter and include the styles needed by that adapter.

    import NgwMap from '@nextgis/ngw-leaflet';
    // Or import NgwMap from '@nextgis/ngw-ol';
    // Or import NgwMap from '@nextgis/ngw-maplibre-gl';

    const ngwMap = await NgwMap.create({
      baseUrl: 'https://demo.nextgis.com',
      target: 'map',
      resources: [{ resource: 2011, fit: true }],
    });

    Use new NgwMap(options) when the instance is needed immediately. Use NgwMap.create(options) when subsequent code requires a fully initialized map.

    Package Use it when
    @nextgis/react-ngw-leaflet A React application needs a ready-to-use Leaflet-based NextGIS Web map.
    @nextgis/react-ngw-ol A React application needs a ready-to-use OpenLayers-based NextGIS Web map.
    @nextgis/react-ngw-maplibre-gl A React application needs a ready-to-use MapLibre GL JS-based NextGIS Web map.
    @nextgis/react-ngw-map A React library or application supplies its own map adapter or uses map context, layer, control, and hook exports directly.

    The three engine-specific components configure their adapter and render the common ReactNgwMap component. Map options are passed as component props. Use whenCreated when application code needs the initialized NgwMap instance.

    import ReactNgwMap from '@nextgis/react-ngw-leaflet';

    export function Map() {
      return (
        <ReactNgwMap
          baseUrl="https://demo.nextgis.com"
          resources={[{ resource: 2011, fit: true }]}
          style={{ width: '100%', height: '100%' }}
        />
      );
    }
    Package Use it when
    @nextgis/qms-leaflet Add QMS TMS/WMS layers or the QMS search control to an existing Leaflet map.
    @nextgis/qms-ol Add QMS TMS/WMS layers or the QMS search control to an existing OpenLayers map.
    @nextgis/qms-maplibre-gl Add QMS TMS/WMS layers or the QMS search control to an existing MapLibre GL JS map.
    @nextgis/qms-core Search and resolve QMS services without a map, or build a custom QMS integration.
    @nextgis/qms-kit Register QMS as a layer adapter in a webmap-based library.

    The engine-specific QMS packages work with native map instances and expose addQmsLayer(), fitQmsService(), and createQmsControl(). They are separate from the ngw-* facade packages; an NgwMap application can usually add a QMS basemap through the qmsId map option instead.

    @nextgis/ngw-map

    NgwMap adds NextGIS Web resources, requests, identification, selection, and the NgwConnector instance to the framework-independent map API. The ready-to-use ngw-leaflet, ngw-ol, and ngw-maplibre-gl classes extend this class and inject their map adapters.

    Use @nextgis/ngw-map directly when building another ready-to-use map package or when an application must provide its own map adapter configuration.

    @nextgis/webmap

    WebMap is the framework-independent map engine. It owns the common lifecycle, layer registry, controls, events, view operations, selection, filtering, and adapter contracts. It does not know how to access NextGIS Web.

    Use it directly when building a map that is not tied to NextGIS Web, creating a new map adapter, or extending the common map behavior.

    For a typical application the calls pass through these layers:

    1. ngw-leaflet, ngw-ol, or ngw-maplibre-gl creates the native map adapter.
    2. ngw-map provides the common NgwMap class and initializes NextGIS Web integration.
    3. ngw-kit converts NextGIS Web resources into map layer adapters and provides resource-specific utilities.
    4. webmap manages common map, layer, control, and event behavior.
    5. The selected map adapter translates common operations to Leaflet, OpenLayers, or MapLibre GL JS.
    6. ngw-connector performs NextGIS Web HTTP requests used by the higher layers or by application code directly.

    React wrappers sit above the ready-to-use ngw-* maps. QMS packages form a separate integration path: qms-core provides map-independent data and shared UI, the engine packages integrate with native maps, and qms-kit integrates with webmap.

    This means an instance imported from a ready-to-use map package includes:

    • NextGIS Web methods from NgwMap, such as addNgwLayer(), fitResource(), feature requests, identification, and connector;
    • common methods inherited from WebMap, such as addLayer(), removeLayer(), showLayer(), hideLayer(), fitBounds(), view methods, controls, and events;
    • adapter-specific options and native objects where an operation cannot be represented by the common API.
    • Start with a ready-to-use ngw-* map package for an end-user map.
    • Start with the matching react-ngw-* package in a React application.
    • Use ngw-connector for resource and feature API calls without a map.
    • Use utilities from ngw-kit when an application needs an operation that is not exposed as an NgwMap convenience method.
    • Use ngw-map to build a new NextGIS Web map distribution or supply a custom adapter.
    • Use webmap to build framework-independent mapping infrastructure.
    • Use an engine-specific qms-* package with an existing native map, or qms-core when no map integration is needed.

    Prefer the common API when it provides the required operation. Keep framework-specific work in the corresponding adapter or ready-to-use package; behavior working in the other adapters should not be changed to fix a problem specific to one rendering engine.

    The available NextGIS Web routes and types depend on the server version and installed components. Generate declarations from the deployment used by the application:

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

    The loader installs resolvable declaration packages under node_modules/@nextgisweb. No generated declaration file needs to be added to tsconfig.json.

    Settings
    Member Visibility

    On This Page
    Package architecture