Skip to content

Module Embed Entry

Jump to bottom Edit New page
niryuu edited this page May 25, 2026 · 1 revision

embed.ts / embed-core.ts — 2 つのエントリポイント

embed パッケージは webpack の entry を 2 つ持つ (webpack.config.js:45-78) ことで、用途別に 2 種類の UMD バンドルを出力する。

エントリ 出力 用途
src/embed.ts dist/embed.js (umd, geoloniaEmbed) <script src="...embed.js?geolonia-api-key=XXX"> で読み込む HTML 宣言的利用
src/embed-core.ts dist/embed-core.js (umd, geoloniaEmbedCore) React wrapper 等のプログラム的利用 (副作用最小)

src/embed.ts (97 行)

embed.js をビルドするときのエントリ。

公開 API (export)

export type { GeoloniaMapOptions } from './lib/geolonia-map';
export type Popup = maplibregl.Popup;
export type { EmbedAttributes, EmbedPlugin } from './types';
export type Geolonia = Partial<typeof maplibregl> & {
  accessToken?: string;
  embedVersion: string;
  Map: typeof GeoloniaMap;
  Marker: typeof GeoloniaMarker;
  SimpleStyle: typeof SimpleStyle;
  simpleStyle: typeof SimpleStyle;  // backward compatibility
  registerPlugin: (embedPlugin: EmbedPlugin) => void;
};

export {
  geolonia,              // Geolonia 型の singleton
  GeoloniaMap as Map,
  GeoloniaMarker as Marker,
  SimpleStyle,
  embedVersion,          // src/version.ts の VERSION
};

副作用

embed.ts がロードされた瞬間に以下を必ず実行する (embed.ts:38-49):

  1. Object.assign(window.geolonia || {}, maplibregl, { Map, Marker, SimpleStyle, simpleStyle, embedVersion, registerPlugin }) で geolonia オブジェクトを構築
  2. window.geolonia = (window.maplibregl as any) = window.mapboxgl = geolonia で 3 つのグローバルに同じ参照を代入 (後方互換: 旧名 mapboxgl で使っているユーザコードでも動くように)
  3. renderGeoloniaMap() を呼び出し (render.ts 内部で DOM 走査開始)

これらはモジュールトップレベルで実行されるので、import だけで効果が発生する。

Geolonia 型の意味

Partial<typeof maplibregl> で maplibregl の全 export (Map, Marker, Popup, NavigationControl, etc.) を optional 含有しているのは、Object.assign(..., maplibregl, ...) で maplibregl 全体を spread しているため。これにより window.geolonia.Popup, window.geolonia.NavigationControl 等が利用可能。

ただし Map / Marker / SimpleStyle は Geolonia 拡張版で上書き (maplibre 標準の Map ではなく GeoloniaMap が入る)。

simpleStyle: typeof SimpleStyle (キャメル小文字版)

simpleStyle (小文字始まり) は古い API の互換性のため (embed.ts:26)。新規コードは SimpleStyle を使う。

src/embed-core.ts (23 行)

embed-core.js をビルドするときのエントリ。

公開 API (export)

export { default as GeoloniaMap } from './lib/geolonia-map';
export { default as GeoloniaMarker } from './lib/geolonia-marker';
export { SimpleStyle } from './lib/simplestyle';
export { default as SimpleStyleVector } from './lib/simplestyle-vector';
export { keyring } from './lib/keyring';
export { registerPlugin } from './lib/render';
export { VERSION as embedVersion } from './version';
export type { EmbedAttributes, EmbedPlugin } from './types';
export type { GeoloniaMapOptions } from './lib/geolonia-map';

embed.ts との比較:

  • embed-core にあって embed.ts に無いもの: SimpleStyleVector (named export), keyring
  • embed.ts にあって embed-core に無いもの: geolonia シングルトン、Geolonia 型、Popup 型 alias、Map/Marker/SimpleStyle の (再) named export
  • 共通: GeoloniaMap, GeoloniaMarker, SimpleStyle, registerPlugin, embedVersion, EmbedAttributes / EmbedPlugin / GeoloniaMapOptions 型

副作用

embed-core.ts:11-12:

const protocol = new Protocol();
maplibregl.addProtocol('pmtiles', protocol.tile);

PMTiles プロトコル登録のみ。renderGeoloniaMap() は呼ばない、window.geolonia への代入もしない。

ただし maplibregl.addProtocol は maplibre のグローバル状態を変更する 副作用。同一ページで embed.js と embed-core.js の両方を読むと二重登録になる可能性 (maplibre 側で例外を投げるか上書きするか要確認)。

embed.ts 側のプロトコル登録

embed-core.ts とは別に、embed.ts 経由でも PMTiles が登録される。場所は render.ts:13-14 の renderGeoloniaMap() 内 (constructor の冒頭):

const protocol = new Protocol();
maplibregl.addProtocol('pmtiles', protocol.tile);

→ embed.ts の場合は renderGeoloniaMap() が呼ばれたタイミングで登録される (constructor 引数の評価開始時)。embed-core.ts は import 時点で登録される。タイミングが違う。

ビルド構成 (webpack.config.js:45-78)

embedConfig

{
  name: 'embed',
  entry: './src/embed.ts',
  output: {
    path: 'dist/',
    filename: 'embed.js',
    chunkFilename: 'embed-chunks/[chunkhash].js',
    clean: true,
    publicPath: 'auto',
    library: { name: 'geoloniaEmbed', type: 'umd' },
  },
}

clean: true なので dist/ 全削除してから出力。

embedCoreConfig

{
  name: 'embed-core',
  dependencies: ['embed'],   // embedConfig を先にビルドする
  entry: './src/embed-core.ts',
  output: {
    path: 'dist/',
    filename: 'embed-core.js',
    chunkFilename: 'embed-chunks/[chunkhash].js',
    clean: false,            // dist/ を保持
    publicPath: 'auto',
    library: { name: 'geoloniaEmbedCore', type: 'umd' },
  },
}

dependencies: ['embed'] で順序保証 (embedConfig の後に動く)、clean: false で先行 build 成果物を残す。

両者は embed-chunks/ を共有するため、コード分割した chunk は両者で重複しない。sanitize-html (util.ts:395 で動的 import) などがここに切り出される。

共通設定 (sharedConfig)

  • ts-loader (tsconfig.build.json)
  • svg-inline-loader で .svg → 文字列 import
  • style-loader + css-loader で .css
  • DefinePlugin で process.env.MAP_PLATFORM_STAGE を静的置換 (デフォルト 'dev')

dist/ の最終構造

dist/
  embed.js                    # UMD, geoloniaEmbed
  embed-core.js               # UMD, geoloniaEmbedCore
  embed-chunks/
    <chunkhash>.js            # 共通 chunk (sanitize-html 等)
  src/                        # .d.ts 群 (tsconfig.build.json declarationDir)
    embed.d.ts
    embed-core.d.ts
    lib/...

package.json:5-15 の exports map:

{
  "main": "dist/embed.js",
  "types": "dist/src/embed.d.ts",
  "exports": {
    ".": {
      "types": "./dist/src/embed.d.ts",
      "default": "./dist/embed.js"
    },
    "./core": {
      "types": "./dist/src/embed-core.d.ts",
      "default": "./dist/embed-core.js"
    }
  }
}

import { GeoloniaMap } from '@geolonia/embed/core' で embed-core.js を引ける。

書き直し時の指針 (詳細は Core-vs-Wrapper)

  • embed-core.ts は将来的に 独立パッケージ maps-core として分離予定
  • embed.ts は thin wrapper になり、DOM 走査・window.geolonia 設定・後方互換代入のみ担う
  • simpleStyle (小文字) や window.mapboxgl への代入などの後方互換は別途扱いを決定する必要あり (削除可? 保持必須?)
Add a custom footer
Add a custom sidebar

Clone this wiki locally