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

1. Replace the JS and CSS import from CDN references.

   MapLibre GL JS

   MapTiler SDK JS

2. Uninstall maplibre-gl and install @maptiler/sdk

Replace maplibregl with maptilersdk

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

MapLibre GL JS

MapTiler SDK JS

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.

MapLibre GL JS

MapTiler SDK JS

Initialize the web map

MapLibre GL JS

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

MapTiler SDK JS

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

Migrate the basemap styles

You can use the MapTiler Cloud 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

MapLibre GL JS

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.

MapTiler SDK JS

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

MapLibre GL JS

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

MapTiler SDK JS

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

MapLibre GL JS

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

MapTiler SDK JS

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

MapLibre GL JS

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

MapTiler SDK JS

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

Change the map’s language

MapLibre GL JS

Change the map language dynamically

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.

Change the default map language

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.

MapTiler SDK JS

Change the map language dynamically

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.

Change the default map language

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

MapLibre GL JS

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.

MapTiler SDK JS

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.

MapLibre GL JS

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

MapTiler SDK JS

The MapTiler logo attribution is automatically added to the map.

Related examples

Weather layer switcher

Example

Switch the display of the different weather layers in the MapTiler Cloud Weather data set and get the data information at the point under the cursor.

Learn the basics

Example

This tutorial shows how to create a map and display it on a web page using MapTiler Cloud.

Switch from Mapbox

Example

This tutorial shows how to migrate/switch from Mapbox to MapTiler.

Start with AR maps

Example

Getting started with AR maps: The Augmented reality (AR) control adds a button on your map to create a 3D model of the viewport, including 3D terrain and any layer you have put on top. Compatible with WebXR or Apple Quick Look.