How to migrate/switch from MapLibre to MapTiler

This tutorial provides guidance on transitioning or changing from MapLibre to MapTiler. If you currently utilize MapLibre GL JS in your application, updating it to use the MapTiler SDK JS is a straightforward process.

In most cases, you can simply uninstall maplibre-gl and install @maptiler/sdk in your node packages or change the CDN links. Additionally, you will need to replace all instances of maplibregl with maptilersdk in your TypeScript, JavaScript, and HTML/CSS code. This ensures a seamless integration of the MapTiler SDK JS into your existing application.

Next, we will see the main changes that must be made to migrate your application from MapLibre to MapTiler.

Installation

Replace maplibregl with maptilersdk

Look in your application and replace maplibregl with maptilersdk in your TypeScript, JavaScript and HTML/CSS files. Some examples below

Replace the api key or accessToken

Find the variable where you store your actual MapTiler API key in the code and replace it with maptilersdk.config.apiKey.

Initialize the web map

With MapLibre GL JS, you initialize a new map like this:

You can initialize a map in a similar way using the MapTiler SDK JS

Migrate the basemap styles

You can use the MapTiler service to provide the basemap for your application. There are different Map styles to choose from such as streets, satellite imagery, outdoor, dataviz, OpenStreetMap, etc. Each style offers a range of variants that contain the same level of information and have the same purpose but use different color schemes like dark, light, etc. You can also create and use your own custom basemap styles by using the customize tool style editor.

Checkout the list of MapTiler SDK JS Map styles

You need to write the full URL of the style. If we make an update to a style (new version), you have to modify your codebase to have the latest version of styles. You must put the API key in every URL.

Always use the latest version of styles. No need to type along style URL. No more putting the API key in every URL.

Map controls

Zoom and rotate controls

To display zoom and rotate controls, you must add the NavigationControl to the map.

The zoom and rotate controls are displayed by default on the map. So there is no need to add the NavigationControl to the map.

Geolocate control

To display the GeolocateControl, you must add the control to the map.

The geolocate control is displayed by default on the map. So there is no need to add the GeolocateControl to the map.

Support for right-to-left languages

To support right-to-left languages such as Arabic and Hebrew you need to add and use the mapbox-gl-rtl-text plugin.

Right-to-left languages are supported by default so there is no need to add any plugins.

Change the map’s language

To change the map language dynamically you have to use the setLayoutProperty method for each of the text layers you have on the map and change the text-field property. This forces you to review the style, find the IDs of the text layers and execute the function for each layer. To avoid doing this you can use the mapbox-gl-language plugin.

To change the default map language (or initial map language), you have to go into the MapTiler Map design tool and modify the map style. You have to do this for each style.

To change the map language dynamically just call the method setLanguage. There’s no need to add any plugins or search for all text layers and change the text-filed property. The SDK does all this automatically for you.

The SDK detects the language of the browser and displays the map in that language. There is no need to modify the style or load any plugin. Check the documentation about languages. If you want to define the initial language of the map, just set the language in the map constructor options.

Add 3D terrain to a map

To add the 3D terrain to a map you have to first add a data source of type raster-dem and then call the map’s setTerrain function.

To activate and deactivate the terrain dynamically you have to use the TerrainControl.

To add the 3D terrain to a map just set the terrain: true in the map constructor options. To activate and deactivate the terrain dynamically add the terrainControl: true in the map constructor options. There’s no need to add a data source or add the terrain control.

MapTiler logo attribution

Free plan maps require the logo. It is required to place the MapTiler logo, with a link to https://maptiler.com/, on all maps in case you are not subscribed to any of the commercial plans of the Service. The MapTiler logo must be visible, readable and should appear in the left bottom corner of the map.

You must have something like this in your application to comply with the MapTiler Terms and Conditions.

The MapTiler logo attribution is automatically added to the map.

Related examples