Skip to content

SmartMaps Migration Guide

This part of the documentation is dedicated to the migration from Mapbox GL to SmartMaps GL.

This guide provides a straightforward approach to transition between the two libraries, which are similar but may diverge with newer features.

Migration Steps

Uninstall Mapbox and install SmartMapsGL

Begin by uninstalling mapbox-gl from your node packages and installing smartmapsgl. You can also use CDN links as shown below.

Replace mapboxgl with smartmapsgl

Update your TypeScript, JavaScript, HTML, and CSS files by replacing all instances of mapboxgl with smartmapsgl.

// Before
mapboxgl.accessToken = "INSERT ACCESS-TOKEN";
var map = new mapboxgl.Map({
    container: 'map', // container ID
    center: [-74.5, 40], // starting position [lng, lat]
    style: "mapbox://styles/mapbox/satellite-streets-v12",
    zoom: 9 // starting zoom
});

// After
var map = new smartmapsgl.Map({
    apiKey: '[INSERT API-KEY]',
    container: 'map', // container ID
    center: [-74.5, 40], // starting position [lng, lat]
    style: smartmapsgl.MapStyle.AUTO,
    zoom: 9 // starting zoom
});

<!-- Before -->
<button class="mapboxgl-ctrl"></button>

<!-- After -->
<button class="smartmapsgl-ctrl"></button>

Replace the Mapbox CDN link with the SmartMapsGL CDN link:

<!-- Before -->
<script src="https://api.mapbox.com/mapbox-gl-js/v#.#.#/mapbox-gl.js"></script>
<link href="https://api.mapbox.com/mapbox-gl-js/v#.#.#/mapbox-gl.css" rel="stylesheet" />

<!-- After -->
<script src="https://cdn.smartmaps.cloud/packages/smartmaps/smartmaps-gl/v2/umd/smartmaps-gl.min.js"></script>

Note that the CSS link is not required for SmartMapsGL because it's included in the UMD module used in this example.

API Keys and Styles

  • API Keys: SmartMaps GL does not use access tokens. It authenticates with an API key, passed as the apiKey map option — so replace the mapboxgl.accessToken assignment instead of porting it over.
  • Map Styles: Update any map style URLs to match those provided by SmartMapsGL.

This guide should help you transition from Mapbox to SmartMaps GL by following similar steps as those used for migrating to MapLibre.