ドキュメント / セットアップ / React / MapTiler

MapTiler セットアップ

Web で MapTiler Cloud のスタイルを MapConductor から使う手順です。レンダラーは maplibre-gl で、スタイルは API キー付きの MapTiler Cloud URL として組み立てられます。

PACKAGE

react-for-maptiler

API KEY

必要

CSS

必要

REACT NATIVE

なし

ほかのプラットフォームAndroid iOS

デモを見る店舗マップ · React ↗

前提

Node.js 18 以上

MapTiler Cloud のアカウントと API キー

STEP 01

インストールする

コアと React バインディング、そしてプロバイダのパッケージを入れます。プロバイダを差し替えるときに変わるのは 3 つ目だけです。

terminalnpm

npm install @mapconductor/js-sdk-core @mapconductor/js-sdk-react \
            @mapconductor/react-for-maptiler

STEP 02

Vite の事前バンドルから外す

Vite を使う場合は optimizeDeps.exclude にプロバイダを追加します。maplibre-gl v6 はワーカーを URL で読み込むため、事前バンドルされると .vite/deps 配下にワーカーのファイルが出力されず、読み込みに失敗します。

vite.config.tsTypeScript · Vite

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
    optimizeDeps: {
        exclude: ["@mapconductor/react-for-maptiler", "@mapconductor/js-sdk-core"],
    },
    plugins: [react()],
});

STEP 03

スタイルシートを読み込む

アプリのエントリーポイントで一度だけ読み込みます。忘れると地図の位置やコントロールの見た目が崩れます。

main.tsxTypeScript

import '@mapconductor/react-for-maptiler/style.css';

STEP 04

API キーを状態フックに渡す

キーはスタイル JSON の URL に組み込まれます（https://api.maptiler.com/maps/<style>/style.json?key=…）。

MapTilerMap.tsxTypeScript · React

const state = useMapTilerViewState({
  apiKey: import.meta.env.VITE_MAPTILER,
  mapDesignType: MapTilerDesign.Streets,
  cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
});

注意

キーはビルド時の環境変数（Vite なら import.meta.env.VITE_*）から渡し、ソース管理には入れないでください。フロントエンドに渡る以上、公開されても被害が出ないようリファラ制限やドメイン制限を必ず掛けます。

動作確認

ここまで動けば完了

MapTiler のスタイルで地図が出れば完了です。

MapTilerMap.tsxTypeScript · React

import { useState } from 'react';
import { createGeoPoint, createMapCameraPosition, createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';
import { MapTilerDesign, MapTilerMapView2D, useMapTilerViewState } from '@mapconductor/react-for-maptiler';
import '@mapconductor/react-for-maptiler/style.css';

const TOKYO = createGeoPoint({ latitude: 35.6812, longitude: 139.7671 });

export function MapTilerMap() {
  const state = useMapTilerViewState({
    apiKey: import.meta.env.VITE_MAPTILER,
    mapDesignType: MapTilerDesign.Streets,
    cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
  });
  const [markerState] = useState(() => createMarkerState({ id: 'tokyo', position: TOKYO }));

  return (
    <MapTilerMapView2D state={state} style={{ height: 480 }}>
      <Marker state={markerState} />
    </MapTilerMapView2D>
  );
}

地図デザイン

MapTilerDesign は MapTiler Cloud の参照スタイルに対応します。

MapTilerDesign

Notes

Streets / StreetsDark / StreetsLight

標準の道路地図と明暗のバリエーション

Basic / Bright

情報量を絞ったスタイル

Satellite

衛星画像

Outdoor / Winter / Topo

アウトドア・冬季・地形

Toner / Dataviz / Backdrop

データを載せる下地向け

Ocean / Landscape / Aquarelle / OpenStreetMap

その他のテーマ別スタイル

うまくいかないとき

地図が真っ白のまま

apiKey が空文字になっていないか確認します。環境変数が読めていないケースが多いです。
MapTiler Cloud でキーが有効か、無料枠を超えていないか確認します。

地図の位置やコントロールが崩れる

style.css を読み込んでいるか確認します。

開発時だけ地図が二重に初期化される

React StrictMode は effect を 2 回実行します。各プロバイダはこれを検知して片方を破棄するようになっているので、StrictMode を外す必要はありません。

次に

MapLibre と同じレンダラーなので、挙動や制約は MapLibre プロバイダと共通です。