maps-react

チュートリアル Step 0: 地図を表示する

maps-react は、Geolonia Maps を React コンポーネントとして扱うためのライブラリです。この Step では、React アプリに地図を1枚表示します。

このチュートリアルのコード例は、#root に対して createRoot() を実行するブラウザ用のエントリーポイントを前提としています。Vite や webpack で構築した環境がこれにあたります。環境の用意がない場合は Vite を使用してください。

Next.js のように React ツリーをフレームワークが構築する環境では、createRoot() は実行しません。Map をクライアントコンポーネントの中に配置してください。

インストールする

maps-react と、地図の描画エンジンである maplibre-gl をインストールします。maplibre-gl は react-map-gl など他の React 向け地図ライブラリの基盤でもあり、maps-react とは別のパッケージとしてインストールします。

npm install @geolonia/maps-react maplibre-gl

地図を表示する

Map コンポーネントと、地図の描画に必要な CSS をインポートし、JSX に配置します。

import "maplibre-gl/dist/maplibre-gl.css";
import "@geolonia/maps-core/css";
import { createRoot } from "react-dom/client";
import { Map } from "@geolonia/maps-react";
import { setWorkerUrl } from "maplibre-gl";
import workerUrl from "maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url";

setWorkerUrl(workerUrl);

createRoot(document.getElementById("root")).render(
  <Map
    apiKey="YOUR-API-KEY"
    containerStyle={{ width: "100%", height: "100vh" }}
  />,
);

上のコードが、そのまま下で動作しています。

記述の要点は次の4点です。

CSS のインポート：maplibre-gl/dist/maplibre-gl.css と @geolonia/maps-core/css の2つが必要です。どちらかが欠けると、コントロールとポップアップの表示が崩れます。
Worker の設定：MapLibre GL JS v6 は、地図の描画を担う Web Worker を実ファイルの URL から読み込みます。多くのバンドラーはそのファイルを出力に含めないため、最初の Map を描画する前に setWorkerUrl でその場所を教える必要があります。上のコードは Vite の書き方です。webpack の場合は @geolonia/maps-core の Worker setup を参照してください。
containerStyle：地図を描画する要素の大きさ。高さが 0 の場合、地図は表示されません。必ず高さを指定します。
apiKey：YOUR-API-KEY は動作確認用のデモキーであり、localhost、GitHub Pages、CodePen などの開発環境とプレビュー環境でのみ地図が描画されます（対象の一覧はデモキーで無料で試せる環境を参照してください。自分のキーの発行は Step 5 で扱います）。

動いたか確認する

npm run dev で開発サーバーを起動し、ブラウザで開くと地図が表示されます。マウスのドラッグで移動し、ホイールで拡大縮小できれば成功です。center を指定していないため、初期表示は maps-react の既定値である世界地図になります。

うまく出ないとき

真っ白で何も出ない → containerStyle の高さが 0 になっていないか確認。親要素が height: 0 の場合も同じです。
コントロールだけが出て、地図が読み込み中のまま → setWorkerUrl の呼び出し漏れ。コンソールに Worker failed to load と出ていれば、これが原因です。
表示が崩れる（コントロールのアイコンの位置がずれるなど）→ CSS のインポート漏れ。2つとも読み込んでいるか確認。

次の Step

以上で、React アプリへの地図の表示は完了です。次の Step 1: 初期位置とズームの設定で、地図の中心座標、拡大率、傾きを props で指定します。