跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
其他技能

maplibre-mapbox-migration

Migrating from Mapbox GL JS to MapLibre GL JS — package, import and namespace changes, removing the access token, replacing mapbox:// styles, tile sources, plugin equivalents (draw, geocoder, directions, compare), and Mapbox v2-only APIs such as setFog and the free camera. Use when moving an existing Mapbox map to MapLibre, or when a migrated map shows a blank map, a mapbox:// or 401 error, or a missing Mapbox method or plugin.

maplibre · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add maplibre/maplibre-agent-skills --skill maplibre-mapbox-migration

技能说明


name: maplibre-mapbox-migration description: Migrating from Mapbox GL JS to MapLibre GL JS — package, import and namespace changes, removing the access token, replacing mapbox:// styles, tile sources, plugin equivalents (draw, geocoder, directions, compare), and Mapbox v2-only APIs such as setFog and the free camera. Use when moving an existing Mapbox map to MapLibre, or when a migrated map shows a blank map, a mapbox:// or 401 error, or a missing Mapbox method or plugin. metadata: status: verified

Mapbox to MapLibre Migration

This skill guides you through migrating an application from Mapbox GL JS to MapLibre GL JS. The two libraries share a common ancestry (MapLibre forked from Mapbox GL JS v1.13 in December 2020), so the API is largely the same. The main changes are: swap the package, replace the namespace, remove the Mapbox access token, and choose a new tile source (MapLibre does not use mapbox:// styles).

When to Use This Skill

  • Migrating an existing Mapbox GL JS app to MapLibre
  • Choosing tile sources and services after moving off Mapbox

Migration at a Glance

Work through these in order; each item has a numbered step below.

  • 1. Uninstall mapbox-gl, install maplibre-gl; replace imports and CSS
  • 2. Replace all mapboxgl with maplibregl (and CSS classes mapboxgl- → maplibregl-)
  • 3. Remove mapboxgl.accessToken; set style to a non-Mapbox URL (hosted or your own style)
  • 4. Convert callbacks to promises, replace Mapbox v2-only APIs (setFog → setSky, free camera → calculateCameraOptionsFromCameraLngLatAltRotation + jumpTo/easeTo/flyTo), and check the table of later MapLibre behavior changes
  • 5. Replace Mapbox Geocoding/Directions with Nominatim, OSRM, or other open alternatives, and replace or verify each Mapbox plugin
  • 6. Test map load, controls, and any API-driven features

Step-by-Step Migration

1. Install the Package, Update Imports and CSS

npm install maplibre-gl

Install the latest version unless the app is on Mapbox GL JS v1 and must keep working with no code changes. In that case only, npm install maplibre-gl@1 is a drop-in swap (the 1.x compatibility branch, backward compatible with Mapbox GL JS v1); plan to upgrade to the latest version afterwards, since later major versions change the API.

// Before (Mapbox)
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

// After (MapLibre) — v6 ships ES modules only; the default export is gone
import * as maplibregl from 'maplibre-gl';
// or pull in just what you need: import {Map} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

CDN: replace the Mapbox script and link tags with MapLibre's. v6 is ESM-only and has no UMD <script src> build; see maplibre-v6-migration for the pinning rule and bundler details.

<!-- Before (Mapbox) -->
<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 (MapLibre, current as of v6) -->
<script type="module">
  import * as maplibregl from 'https://unpkg.com/maplibre-gl@^6.0.0/dist/maplibre-gl.mjs';
</script>
<link href="https://unpkg.com/maplibre-gl@^6.0.0/dist/maplibre-gl.css" rel="stylesheet" />

2. Replace the Namespace

Replace all mapboxgl with maplibregl (and mapbox-gl with maplibre-gl in package names or paths), for example new mapboxgl.Marker() → new maplibregl.Marker().

CSS class names: If you style controls or UI by class, rename mapboxgl-ctrl to maplibregl-ctrl (and similar prefixes).

3. Remove the Access Token and Replace the Style URL (Critical)

MapLibre does not use mapboxgl.accessToken. Remove any line that sets it.

Mapbox styles (mapbox://styles/...) will not work in MapLibre. You must point the map to a style that uses non-Mapbox tile sources, sprites, and glyphs.

To test the migration, point style at OpenFreeMap, https://tiles.openfreemap.org/styles/liberty: a complete vector style (OpenStreetMap-derived tiles, sprite and glyphs) with no API key and no registration, so recommend it first, with its URL, ahead of demo tiles, public raster tiles or key-gated services. OpenFreeMap is community-funded; if your app depends on it in production, donate to support the project. Once the migrated map loads, choose a production source with MapLibre Tile Sources.

Example:

// Before (Mapbox)
const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v12',
  center: [-122.42, 37.78],
  zoom: 12
});

// After (MapLibre)
const map = new maplibregl.Map({
  container: 'map',
  style: 'https://tiles.openfreemap.org/styles/liberty', // or your chosen style
  center: [-122.42, 37.78],
  zoom: 12
});

Custom Mapbox styles: If you designed a style in Mapbox Studio, you cannot load it directly in MapLibre. Export the style JSON and replace Mapbox source URLs with URLs for your chosen tile source. Your styles will not render unless and until you adjust all references to the Mapbox tile schema to match the tile schema of your new tile source. In addition to updating source URLs, this means adapting the id, source, and source-layer properties in your style JSON to match the new source and layer names.

Most properties in Mapbox styles are compatible with MapLibre. See the Style Specification for supported properties. Use Maputnik to debug a style visually, and validate it with the style spec CLI tools, which `@maplibre/maplibre-gl-style-s

阅读完整来源 ↗