maps-react

チュートリアル 段0：地図を出す

maps-react チュートリアルへようこそ。maps-react は、Geolonia Maps を React コンポーネントとして使うためのライブラリです。この段では、React アプリに地図を1枚出すところまでをやります。

React のビルド環境（Vite、Next.js、webpack など）ならほとんどそのまま動きます。まだ環境がない方は Vite で作るのが手軽です。

インストールする

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つです。

動いたか確認する

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 では通常不要）。

次は

地図は出ました。でも、見たいのは既定の場所ではなく自分の場所のはずです。次の段1：場所と視点で、地図の中心、拡大率、傾きを props で指定します。