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";

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

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

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

CSS のインポート：maplibre-gl/dist/maplibre-gl.css と @geolonia/maps-core/css の2つが必要です。どちらかが欠けると、コントロールとポップアップの表示が崩れます。
containerStyle：地図を描画する要素の大きさ。高さが 0 の場合、地図は表示されません。必ず高さを指定します。
apiKey：YOUR-API-KEY は動作確認用のデモキーであり、localhost、GitHub Pages、CodePen などの開発環境とプレビュー環境でのみ地図が描画されます（対象の一覧はデモキーで無料で試せる環境を参照してください。自分のキーの発行は Step 5 で扱います）。

動いたか確認する

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

うまく出ないとき

真っ白で何も出ない → containerStyle の高さが 0 になっていないか確認。親要素が height: 0 の場合も同じです。
表示が崩れる（コントロールのアイコンの位置がずれるなど）→ CSS のインポート漏れ。2つとも読み込んでいるか確認。
コンソールに The requested module '.../maplibre-gl.js' does not provide an export named 'default' と出る → maplibre-gl が CJS 形式で配布されており、一部のビルド環境で事前バンドルの対象にならないことが原因です。Astro など Vite ベースの環境では、設定に vite: { optimizeDeps: { include: ['maplibre-gl', '@geolonia/maps-core'] } } を追加すると解消します（Vite 単体の SPA では通常不要です）。

次の Step

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