Mapbox インテグレーションパターンスキル

このスキルは、React、Vue、Svelte、Angular、および Vanilla JavaScript を使用した Web アプリケーションへの Mapbox GL JS インテグレーション用の公式パターンを提供します。これらのパターンは Mapbox の create-web-app スカッフォルディングツールに基づいており、本番環境対応のベストプラクティスを表しています。

バージョン要件

Mapbox GL JS

推奨: v3.x (最新)

• 最小: v3.0.0
• v3.x を推奨する理由: モダンな API、改善されたパフォーマンス、アクティブな開発
• v2.x: レガシー；アクティブ開発終了（以下のマイグレーション注記参照）

npm でのインストール（本番環境推奨）:

npm install mapbox-gl@^3.0.0    # 最新 v3.x をインストール

CDN（プロトタイピング用のみ）:

<!-- VERSION を https://docs.mapbox.com/mapbox-gl-js/ から最新 v3.x に置き換える -->
<script src="https://api.mapbox.com/mapbox-gl-js/vVERSION/mapbox-gl.js"></script>
<link href="https://api.mapbox.com/mapbox-gl-js/vVERSION/mapbox-gl.css" rel="stylesheet" />

フレームワーク要件

React: GL JS は React 16.8+ に対応（フック必須）。create-web-app は React 19.x でスカッフォルドします。 Vue: GL JS は Vue 2.x+ に対応（Vue 3 Composition API 推奨）。 Svelte: GL JS はすべての Svelte バージョンに対応。create-web-app は Svelte 5.x でスカッフォルドします。 Angular: GL JS は Angular 2+ に対応。create-web-app は Angular 19.x でスカッフォルドします。 Next.js: 最小 13.x (App Router)、Pages Router 12.x+。

Mapbox Search JS

npm install @mapbox/search-js-react@^1.0.0      # React
npm install @mapbox/search-js-web@^1.0.0        # その他のフレームワーク

バージョンマイグレーション注記（v2.x から v3.x）

• WebGL 2 が必須に
• optimizeForTerrain オプション削除
• TypeScript 型の改善、より良いツリーシェイキング対応
• コア初期化パターンに破壊的変更なし

トークンパターン（v2.x および v3.x で動作）:

const token = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN; // 本番環境では環境変数を使用

// グローバルトークン（v1.x 以来動作）
mapboxgl.accessToken = token;
const map = new mapboxgl.Map({ container: '...' });

// マップごとのトークン（マルチマップセットアップに推奨）
const map = new mapboxgl.Map({
  accessToken: token,
  container: '...'
});

コア原則

すべての Mapbox GL JS インテグレーションは以下を実装する必要があります：

1. 正しいライフサイクルフックでマップを初期化
2. マップインスタンスをコンポーネント状態に保存（毎回レンダリング時に再作成しない）
3. クリーンアップ時に必ず map.remove() を呼び出す メモリリークを防ぐため
4. トークン管理をセキュアに処理（環境変数）
5. CSS をインポート: import 'mapbox-gl/dist/mapbox-gl.css'

React インテグレーション（プライマリパターン）

パターン: useRef + useEffect とクリーンアップ

注記: これらの例では Vite（create-web-app で使用されるバンドラー）を使用しています。Create React App を使用している場合は、import.meta.env.VITE_MAPBOX_ACCESS_TOKEN を process.env.REACT_APP_MAPBOX_TOKEN に置き換えてください。その他のバンドラーについては Token Management Patterns を参照してください。

import { useRef, useEffect } from 'react';
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

function MapComponent() {
  const mapRef = useRef(null); // マップインスタンスを保存
  const mapContainerRef = useRef(null); // DOM 参照を保存

  useEffect(() => {
    mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;

    mapRef.current = new mapboxgl.Map({
      container: mapContainerRef.current,
      center: [-71.05953, 42.3629],
      zoom: 13
    });

    // 重要: メモリリークを防ぐため、クリーンアップを実施
    return () => {
      mapRef.current.remove();
    };
  }, []); // 空の依存配列 = マウント時に 1 回実行

  return <div ref={mapContainerRef} style={{ height: '100vh' }} />;
}

重要なポイント:

• マップインスタンスとコンテナの両方に useRef を使用
• 空の依存配列 [] で useEffect 内で初期化
• 常にクリーンアップ関数を返す map.remove() を呼び出すため
• レンダリング内でマップを初期化しない（無限ループの原因）

React + Search JS

import { useRef, useEffect, useState } from 'react';
import mapboxgl from 'mapbox-gl';
import { SearchBox } from '@mapbox/search-js-react';
import 'mapbox-gl/dist/mapbox-gl.css';

const accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;
const center = [-71.05953, 42.3629];

function MapWithSearch() {
  const mapRef = useRef(null);
  const mapContainerRef = useRef(null);
  const [inputValue, setInputValue] = useState('');

  useEffect(() => {
    mapboxgl.accessToken = accessToken;

    mapRef.current = new mapboxgl.Map({
      container: mapContainerRef.current,
      center: center,
      zoom: 13
    });

    return () => {
      mapRef.current.remove();
    };
  }, []);

  return (
    <>
      <div
        style={{
          margin: '10px 10px 0 0',
          width: 300,
          right: 0,
          top: 0,
          position: 'absolute',
          zIndex: 10
        }}
      >
        <SearchBox
          accessToken={accessToken}
          map={mapRef.current}
          mapboxgl={mapboxgl}
          value={inputValue}
          proximity={center}
          onChange={(d) => setInputValue(d)}
          marker
        />
      </div>
      <div ref={mapContainerRef} style={{ height: '100vh' }} />
    </>
  );
}

Search JS インテグレーション概要

インストール:

npm install @mapbox/search-js-react      # React
npm install @mapbox/search-js-web        # Vanilla/Vue/Svelte

両方のパッケージは @mapbox/search-js-core を依存関係として含みます。カスタム検索 UI を構築する場合のみ、-core を直接インストールしてください。

キー設定オプション:

• accessToken: Mapbox パブリックトークン
• map: マップインスタンス（事前に初期化する必要があります）
• mapboxgl: mapboxgl ライブラリ参照
• proximity: 地理的に結果をバイアスする [lng, lat]
• marker: 結果マーカーを表示/非表示するブール値
• placeholder: 検索ボックスのプレースホルダーテキスト

検索ボックスの配置

絶対位置指定（オーバーレイ）:

<div
  style={{
    position: 'absolute',
    top: 10,
    right: 10,
    zIndex: 10,
    width: 300
  }}
>
  <SearchBox {...props} />
</div>

一般的な位置:

• 右上: top: 10px, right: 10px
• 左上: top: 10px, left: 10px
• 左下: bottom: 10px, left: 10px

よくある間違い（重要）

間違い 1: map.remove() の呼び出し忘れ

// 悪い例 - メモリリーク！
useEffect(() => {
  const map = new mapboxgl.Map({ ... })
  // クリーンアップ関数なし
}, [])

// 良い例 - 適切なクリーンアップ
useEffect(() => {
  const map = new mapboxgl.Map({ ... })
  return () => map.remove()  // クリーンアップ
}, [])

理由: 各マップインスタンスは WebGL コンテキスト、イベントリスナー、DOM ノードを作成します。クリーンアップなしで、これらが蓄積してメモリリークを引き起こします。

間違い 2: レンダリング内でのマップ初期化

// 悪い例 - React で無限ループ！
function MapComponent() {
  const map = new mapboxgl.Map({ ... })  // 毎回のレンダリングで実行
  return <div />
}

// 良い例 - エフェクト内で初期化
function MapComponent() {
  useEffect(() => {
    const map = new mapboxgl.Map({ ... })
  }, [])
  return <div />
}

理由: React コンポーネントは頻繁に再レンダリングされます。毎回レンダリング時に新しいマップを作成すると、無限ループとクラッシュが発生します。

間違い 3: マップインスタンスを適切に保存しない

// 悪い例 - マップ変数がレンダリング間で失われる
function MapComponent() {
  useEffect(() => {
    let map = new mapboxgl.Map({ ... })
    // マップ変数に後からアクセスできない
  }, [])
}

// 良い例 - useRef に保存
function MapComponent() {
  const mapRef = useRef()
  useEffect(() => {
    mapRef.current = new mapboxgl.Map({ ... })
    // mapRef.current はコンポーネント全体でアクセス可能
  }, [])
}

理由: レイヤー追加、マーカー追加、remove() 呼び出しなどの操作のため、マップインスタンスにアクセスする必要があります。

間違い 4: マップインスタンスを Vue の data() に保存（Vue 固有）

// 悪い例 - Vue のリアクティビティが data() オブジェクトを Proxy でラップし、mapbox-gl の内部を破壊！
export default {
  data() {
    return {
      map: null  // Proxy でラップされる
    }
  },
  mounted() {
    this.map = new mapboxgl.Map({ ... })  // Proxy が GL 内部を破壊
  }
}

// 良い例 - マップをプレーンなインスタンスプロパティとして割り当て、data() には含めない
export default {
  mounted() {
    this.map = new mapboxgl.Map({
      container: this.$refs.mapContainer,
      center: [-71.05953, 42.3629],
      zoom: 13
    })
  },
  unmounted() {
    this.map?.remove()
  }
}

理由: Vue（特に Vue 3）では、data() プロパティはリアクティビティのため Proxy でラップされます。Mapbox GL JS は内部的にオブジェクトアイデンティティをチェックし、プロキシラップを生き残らないプロパティを使用します。マップを data() に保存すると、微妙で デバッグが難しい障害が発生します。代わりに、mounted() でマップインスタンスを直接 this.map として割り当てます — data() 外で割り当てられたプロパティはリアクティブにはなりません。

リファレンスファイル

フレームワーク固有のパターンと追加詳細について、以下をロードしてください：

• references/vue.md — Vue インテグレーション（mounted/unmounted ライフサイクル）
• references/svelte.md — Svelte インテグレーション（onMount/onDestroy）
• references/angular.md — Angular インテグレーション（SSR ハンドリング付き）
• references/vanilla.md — Vanilla JS（Vite）+ Vanilla JS（CDN）
• references/web-components.md — Web Components（基本 + リアクティブ + React/Vue/Svelte での使用）
• references/nextjs.md — Next.js App Router + Pages Router
• references/common-mistakes.md — よくある間違い 4-7 + テストパターン
• references/token-management.md — バンドラーごとのトークン管理 + スタイル設定

このスキルを使用するタイミング

このスキルは以下の場合に呼び出します：

• 新しいプロジェクトで Mapbox GL JS をセットアップ
• Mapbox を特定のフレームワーク（React、Vue、Svelte、Angular、Next.js）に統合
• フレームワーク非依存の Web Components を構築
• コンポーネントライブラリ用の再利用可能なマップコンポーネントを作成
• マップ初期化の問題をデバッグ
• Mapbox Search 機能を追加
• 適切なクリーンアップとライフサイクル管理を実装
• フレームワーク間の変換（例：React から Vue）
• Mapbox インテグレーションのベストプラクティスについてコードをレビュー

関連スキル

• mapbox-cartography: マップ設計原則とスタイリング
• mapbox-token-security: トークン管理とセキュリティ
• mapbox-style-patterns: 一般的なマップスタイルパターン

リソース

• Mapbox GL JS ドキュメント
• Mapbox Search JS ドキュメント
• create-web-app GitHub