mapcn

mapcn

このスキルを使う場面

ユーザーが React + shadcn/ui のコードベースに mapcn をインストール、統合、カスタマイズ、またはトラブルシューティングする必要がある場合に、このスキルを使います。

よくあるきっかけ：

• integrate mapcn
• add mapcn to shadcn project
• mapcn MapControls/Markers/Routes/Clusters
• controlled map viewport with mapcn
• useMap hook mapcn
• MapLibre with mapcn components

ライブラリの概要

mapcn は、MapLibre GL JS を基盤とし、shadcn/ui のワークフローに沿った、コピーして使えるスタイルのマップコンポーネントを提供します。

前提条件：

• プロジェクトで React を使用していること。
• Tailwind CSS の設定が完了していること。
• shadcn/ui の設定が完了していること。

デフォルトの動作：

• mapcn はデフォルトで無料の CARTO タイルを使用します。
• デフォルトのタイル設定では API キーは不要です。

インストール

標準のインストールコマンド：

npx shadcn@latest add @mapcn/map

想定される統合結果：

• UI マップコンポーネントがプロジェクトに追加されます（通常は components/ui の下）。
• 通常、インポートは次の形式になります。

import { Map } from "@/components/ui/map";

クイックスタート

高さを固定したコンテナを使い、Map と MapControls をレンダリングします。

import { Map, MapControls } from "@/components/ui/map";

export function BasicMap() {
  return (
    <div className="h-[500px] w-full overflow-hidden rounded-xl border">
      <Map
        initialViewState={{
          longitude: -58.3816,
          latitude: -34.6037,
          zoom: 11,
        }}
      >
        <MapControls
          showZoom
          showCompass
          showLocate
          showFullscreen
          position="top-right"
        />
      </Map>
    </div>
  );
}

重要：

• マップコンテナには明示的な高さを設定する必要があります。設定しないと、マップが空白で表示されることがあります。

コアコンポーネント

Map と制御されたビューポート

単純なケースでは非制御モードを使い、状態の同期が必要な場合は制御モードを使います。

const [viewport, setViewport] = useState({
  longitude: -58.3816,
  latitude: -34.6037,
  zoom: 11,
});

<Map viewport={viewport} onViewportChange={setViewport} />

コントロール

MapControls は、よく使われる切り替え項目と配置をサポートします。

• showZoom
• showCompass
• showLocate
• showFullscreen
• position

マーカーとマーカー UI ファミリー

より豊かな UI を構成するには、次のマーカーコンポーネントを組み合わせます。

• MapMarker
• MarkerContent
• MarkerPopup
• MarkerTooltip
• MarkerLabel

単独のポップアップ

マーカーコンポーネントに厳密には紐づかないポップアップ UI には、MapPopup を使います。

ルート

MapRoute を使うと、経路ベースのオーバーレイやルート状のラインを描画できます。

クラスター

密集したポイントデータセットには、GeoJSON 入力とともに MapClusterLayer を使います。

高度な統合

MapRef

flyTo、カスタムのカメラ遷移、マップインスタンスへの直接操作など、命令型のマップ操作には MapRef を使います。

useMap

useMap を使うと、マップのコンテキストに安全にアクセスし、ライフサイクルを考慮したクリーンアップとともにイベントリスナーを登録できます。

カスタムスタイル

デフォルトのタイルでは不十分な場合は、MapLibre 互換のスタイル URL／仕様とともに styles プロパティ（または対応するマップスタイル設定オプション）を使います。

パフォーマンスのガイドライン

• DOM マーカーは、少数から中程度の件数（通常は数百ポイントまで）に適しています。
• 大規模なデータセットでは、GeoJSON レイヤーベースのレンダリングとクラスタリング（MapClusterLayer）を優先します。
• プロパティとハンドラーを安定させ、過剰な再レンダリングを避けます。
• 高度なマップイベントを使う場合は、必ずイベントリスナーをクリーンアップします。

トラブルシューティング

マップが空白になる

次の点を確認します。

• コンテナに明示的な高さが設定されていること。
• スタイル URL／仕様が有効であること。
• タイルのリクエストがブロックされていないこと（ネットワーク／CORS）。

ハイドレーション／アプリフレームワークの問題

• SSR を使用するアプリ構成では、マップのレンダリングがクライアントで安全に行われることを確認します。
• マウント前にマップインスタンスへ直接アクセスしないでください。

コントロールまたはマーカーが表示されない

• コンポーネントが適切なマップコンテキストの下にネストされていることを確認します。
• マーカーおよびポップアップコンポーネントの想定される子要素の階層を確認します。

型／座標のエラー

• 座標の形式と順序、およびプロパティの型を検証します。
• コールバックのシグネチャをコンポーネントの想定に合わせます。

エージェントのワークフロー

1. ユーザーの意図を特定します：インストール、基本的なマップ、マーカー、ポップアップ、ルート、クラスター、高度なイベント。
2. まず最小限の動作する統合を実装します。
3. 状態の同期が必要な場合にのみ、制御されたビューポートに切り替えます。
4. ポイント数が増えたら、クラスター／レイヤーパターンに切り替えます。
5. 簡潔なコードを提示してから、判断の理由と次の手順を説明します。

対象外

• React 以外のフレームワーク。
• 依頼されていないラッパーの移行や比較作業。
• mapcn のデフォルト設定／キー不要の基本範囲を超える、ホスト型マップベンダーのアカウント設定。

References

Local references:

• references/docs-pages.md
• references/api-cheatsheet.md

Canonical docs:

• https://www.mapcn.dev/docs
• https://www.mapcn.dev/docs/installation
• https://www.mapcn.dev/docs/api-reference
• https://www.mapcn.dev/docs/basic-map
• https://www.mapcn.dev/docs/controls
• https://www.mapcn.dev/docs/markers
• https://www.mapcn.dev/docs/popups
• https://www.mapcn.dev/docs/routes
• https://www.mapcn.dev/docs/clusters
• https://www.mapcn.dev/docs/advanced-usage