Get Started

Learn how to integrate @sovereignsolutions/ss-map-gl into your web application using standard package managers or CDN links.

Single package

The map engine is bundled inside @sovereignsolutions/ss-map-gl - there is no separate MapLibre GL peer dependency to install, version, or keep in sync.

Package Manager Installation

Install @sovereignsolutions/ss-map-gl. That's the only install you need - the map engine is included:

npm
Yarn
pnpm

npm install @sovereignsolutions/ss-map-gl

yarn add @sovereignsolutions/ss-map-gl

pnpm add @sovereignsolutions/ss-map-gl

Usage in Bundlers (ESM / TypeScript / React / Vue)

Import the map and any of the built-in classes from the root package, plus the CSS stylesheet (one file - it already includes the map engine's CSS and the drawing toolbar's CSS):

import { Map, Marker, NavigationControl, MapEngine, ClusterController } from '@sovereignsolutions/ss-map-gl';
import { DrawingController } from '@sovereignsolutions/ss-map-gl/drawing';
import '@sovereignsolutions/ss-map-gl/dist/ss-map-gl.css';

const map = new Map({ container: 'map', style: 'DARK', apiKey: 'your_sovereign_api_key' });
map.addControl(new NavigationControl());
new Marker().setLngLat([77.209, 28.6139]).addTo(map);

const drawingController = new DrawingController(map, { showToolbar: true });

DrawingController and the drawing modes live under the /drawing subpath, so consumers who never draw don't pay for the drawing engine in their bundle.

CDN Usage (Vanilla JavaScript / HTML)

A single <script> tag is enough - everything the SDK needs is bundled in, so no other <script> tags are required:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Sovereign Maps SDK</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@sovereignsolutions/ss-map-gl/dist/ss-map-gl.css">
  <style>#map { width: 100vw; height: 100vh; }</style>
</head>
<body>
  <div id="map"></div>

  <script src="https://cdn.jsdelivr.net/npm/@sovereignsolutions/ss-map-gl/dist/ss-map-gl.umd.js"></script>
  <script>
    // Everything is available under the global SSMapGL namespace
    const map = new SSMapGL.Map({ container: 'map', center: [78.9629, 20.5937], zoom: 5 });
    map.addControl(new SSMapGL.NavigationControl());

    const drawController = new SSMapGL.DrawingController(map);
  </script>
</body>
</html>

`Map` vs `MapEngine`

MapEngine (used throughout the rest of this guide) is a small convenience wrapper around Map - mapEngine.map is a real Map instance - adding onDrag/onZoom/onBoundsChange callbacks, getBounds(), setCenter()/setZoom() with easing, and getMyLocation() (browser geolocation). Use Map directly if you'd rather work with its event-driven API surface (.on(...), etc.) as-is; use MapEngine for the extra convenience methods. DrawingController and ClusterController accept either one.

Open Ecosystem Compatibility

Map implements the same open MapLibre GL interface as any standard MapLibre map, so tools built for that open ecosystem work with ss-map-gl unmodified: the MapLibre geocoder, pmtiles's addProtocol, @deck.gl/mapbox's MapboxOverlay, terra-draw, and framework bindings like react-map-gl (pass this package as its mapLib) or vue-maplibre-gl. There's only ever one map engine instance on the page - your package manager dedupes it automatically, the same way it would any shared dependency.

tip

If you ever see more than one copy reported by your package manager's dependency listing, add a resolution/override pinning everything to the same major version.

Next steps

Basic Map Initialization - full working example with lifecycle handling and event hooks
Sample apps - reference source code on GitHub

Package Manager Installation​

Usage in Bundlers (ESM / TypeScript / React / Vue)​

CDN Usage (Vanilla JavaScript / HTML)​

Map vs MapEngine​

Open Ecosystem Compatibility​

Next steps​