【MapLibre GL JS】v6.0.0の主要な変更点とv5からの移行ガイド

初めに

WebGISの開発等でMapLibre GL JSを使用しているが、メジャーアップデートであるv6.0.0がリリースされ、モジュール配信方式の抜本的な刷新やAPIの型安全性向上に伴う破壊的変更（Breaking Changes）が多く含まれていることがわかった。そのため、既存プロジェクトからの移行の代替手段や対応方法として、公式のMigration Guideを参考に変更点をまとめることにした。

v6.0.0より、UMDおよびCSPビルド（maplibre-gl.js, maplibre-gl-csp.js）が廃止されました。既存のシステムから移行する場合は、読み込み方式やインポート構文の修正が必須となります。

リリースノートより意訳
v6.0.0は、ESM（ECMAScript Module）への完全移行、イベントの完全クラス化、新しいベクタータイル規格（MLT）のサポートなどを含むメジャーリリースです。

環境

• MapLibre GL JS 6.0.0

主な変更点（パラメータ・仕様）

• UMD・CSPビルド(廃止) => ESM（maplibre-gl.mjs）へ完全一本化
• styleimagemissingイベント => 通知専用に変更（画像追加は別メソッドへ移行）
• map.transform(削除) => 内部プロパティへの直接アクセス不可。map.getCenter()などの公開APIを使用する
• マップイベント => 全て実体を持つクラス化に変更（包括的だったMapDataEventは削除）

本コード例では環境に合わせた読み込み方法と、APIの移行例をセットしてください。
※HTMLの<script>タグで読み込む場合は、type="module"属性が必須となるため注意すること。

コード（読み込み方式の移行）

index.html

<!-- v5までの読み込み -->
<script src="https://unpkg.com/maplibre-gl@5.0.0/dist/maplibre-gl.js"></script>

<!-- v6からの読み込み（拡張子が.mjsに変更、type="module"が必須） -->
<script type="module" src="https://unpkg.com/maplibre-gl@6.0.0/dist/maplibre-gl.mjs"></script>

app.js

// v5までの書き方（デフォルトインポートはエラーになる）
import maplibregl from 'maplibre-gl';

// v6からの書き方（名前空間インポート）
import * as maplibregl from 'maplibre-gl';

// または名前付きインポートを使用する
import { Map, NavigationControl } from 'maplibre-gl';

API変更の対応例

地図上にアイコンなどを動的に追加する際の実装が大きく変わっている。

image_resolver.js

// v5までの実装（styleimagemissingイベント内で追加）

map.on('styleimagemissing', (e) => {
    const id = e.id;
    const image = generateImage(id); 
    map.addImage(id, image);
});


// v6からの実装（非同期処理もサポートされた専用メソッドを使用）
map.setMissingStyleImageResolver(async (id) => {
    const image = await fetchImageSomehow(id); // 任意の画像取得処理
    return { data: image, pixelRatio: 1 };
});

終わりに

このアップデートに対応することで、TypeScript環境下での型安全性が大幅に向上し、モダンなESM環境での開発が楽になった。移行にあたってはインポート文の修正など手動ですべき箇所もあるが、今後のメンテナンス性を考えると非常に有用なアップデートだと思う。

MapLibre GL JS v6には他にも、新しいベクタータイルフォーマットであるMapLibre Tiles (MLT)のサポートや、fill-layer-opacityプロパティによるレイヤー全体の透過度設定、OSのアクセシビリティ設定に連動するreduceMotionなど非常に有用な機能が多くある。今後もさまざまな機能を使ってより高度な空間データの可視化を試してみたいと思う。

使用にあたっては既存のカスタムシェーダー等に残存しているMapboxへの参照（#pragma mapboxなど）がないかなど、詳細は公式のマイグレーションガイドを読んでお使いください。

参考サイト

https://github.com/maplibre/maplibre-gl-js/blob/main/MIGRATION_GUIDE.md

https://github.com/maplibre/maplibre-gl-js/releases