Skip to content

Development Guide

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

開発ガイド

セットアップ

git clone git@github.com:geolonia/embed.git
cd embed
npm ci             # package-lock.json 厳密準拠

.nvmrc で Node.js のバージョンが指定されている (cat .nvmrc で確認)。nvm use 推奨。

開発サーバ

npm start

内部: MAP_PLATFORM_STAGE=v1 webpack serve --config ./docs/webpack.config.js

  • docs/webpack.config.js を使用 (root の webpack.config.js を拡張)
  • docs/ ディレクトリを serve (port 3000)
  • bundle ファイル embed は dev 用に docs/ に出力
  • watch モードで src/ の変更を反映

URL: http://localhost:3000/ でデモページ。/e2e/ で e2e 用 HTML ページ。

ビルド

npm run build

内部: npm run build:version && npm run build:embed

  • build:version: scripts/build-version.mjs で package.json の version を読み src/version.ts を生成
  • build:embed: MAP_PLATFORM_STAGE=v1 webpack --mode production && cp ./dist/embed.js ./dist/embed && cp -r ./dist/* ./docs/ && rm -rf ./docs/*.d.ts ./docs/lib/

出力:

  • dist/embed.js (UMD, geoloniaEmbed)
  • dist/embed.js のコピー dist/embed (拡張子なし、CDN 用)
  • dist/embed-core.js (UMD, geoloniaEmbedCore)
  • dist/embed-chunks/<chunkhash>.js (共通 chunk)
  • dist/src/**/*.d.ts (TypeScript 型定義)

その後 dist/* を docs/ にコピー (デモ用)。.d.ts と lib/ は docs にコピーしない。

bundle 分析

npm run analyze

ANALYZE=true MAP_PLATFORM_STAGE=v1 webpack --mode production。webpack-bundle-analyzer でブラウザに表示。

テスト

ユニットテスト

npm test

vitest run で src/**/*.test.ts を実行。jsdom 環境 (@types/jsdom + jsdom)。

特定パターンのみ:

npm test -- --grep "pattern"

ファイル単位:

npm test -- src/lib/keyring.test.ts

E2E テスト

npm run e2e

playwright test で e2e/*.spec.ts を実行。chromium のみ。

詳細は E2E-Plan 参照。

初回セットアップ

npx playwright install chromium

E2E 失敗時に browserType.launch: Executable doesn't exist エラーが出たら未インストール。

主要オプション

npx playwright test --reporter=list                  # 詳細出力
npx playwright test e2e/basic.spec.ts                # 単一ファイル
npx playwright test --grep "1.1"                     # パターン match
npx playwright test --headed                         # ブラウザ表示モード
npx playwright test --debug                          # ステップ実行
npx playwright test --trace=on                       # トレース取得

トレース閲覧:

npx playwright show-trace test-results/<path>/trace.zip

Lint / Format

npm run lint    # eslint で全 .ts / .tsx をチェック
npm run format  # prettier で src/**/*.ts を上書き整形

eslint.config.js (flat config) と .prettierrc.json を参照。

ステージ環境変数

MAP_PLATFORM_STAGE は build-time に webpack DefinePlugin で静的置換される (webpack.config.js:7)。ランタイム可変ではない。

コマンド 設定値
npm start v1
npm run build v1
npm run analyze v1
npm run e2e (内部で npm start を起動するので v1)
npx webpack --mode production (直接) dev (デフォルト)

v1 = production stage (本番 API)、dev = development stage (dev API)。書き直し時にランタイム可変化を検討中 (Core-vs-Wrapper 参照)。

依存ライブラリ調査時の注意

node_modules の grep 結果を根拠に診断する前に必ず npm install で実体整合性を確認。

cat node_modules/<pkg>/package.json | grep version
# 想定と異なれば
npm install

過去に maplibre-gl の tileManagers / sourceCaches 周りでこれを怠り誤診断した経緯あり (issue #487)。

主要 npm scripts

{
  "start": "MAP_PLATFORM_STAGE=v1 webpack serve --config ./docs/webpack.config.js",
  "build": "npm run build:version && npm run build:embed",
  "build:version": "node ./scripts/build-version.mjs",
  "build:embed": "MAP_PLATFORM_STAGE=v1 webpack --mode production && cp ./dist/embed.js ./dist/embed && cp -r ./dist/* ./docs/ && rm -rf ./docs/*.d.ts ./docs/lib/",
  "analyze": "ANALYZE=true MAP_PLATFORM_STAGE=v1 webpack --mode production",
  "format": "prettier \"./src/**/*.ts\" --write",
  "lint": "eslint .",
  "test": "vitest run",
  "e2e": "playwright test"
}

TypeScript 設定

ファイル 用途
tsconfig.json エディタ / 開発用 (ts-loader でも参照?)
tsconfig.build.json webpack ビルド用 (webpack.config.js:29)。declarationDir: "dist" 指定で dist/src/**/*.d.ts を生成

CI

.github/workflows/build.yml で:

  • npm ci で依存インストール
  • npm test (ユニット)
  • npm run e2e (E2E、PR #480 で追加)
  • master への push でビルドして CDN にデプロイ (詳細は workflow 参照)

CI では playwright.config.ts の retries: 2 と workers: 1 が有効。

ワークフロー (issue → code → PR)

このリポジトリでは以下のルールを採用 (root Home 参照):

  • すべての作業は issue → code → PR の順で進める
  • PR はすべて master ブランチへのマージ
  • 次の作業が直前の PR のマージに依存する場合は、マージされるまで作業を止める

複数フェーズに分かれる作業 (例: E2E 拡充) は umbrella issue (例: #411) を立て、各フェーズで子 issue を起票して umbrella にリンクする運用。

詳細は E2E-Plan の Issue / PR 分割方針節。

主要ディレクトリ

embed/
├── src/                  # ソース TS
├── e2e/                  # Playwright テスト
├── docs/                 # webpack dev server の root + ビルド成果物のコピー先
│   ├── e2e/              # E2E 用 HTML ページ
│   └── webpack.config.js # dev サーバ用設定
├── dist/                 # webpack 出力 (`.gitignore` 済)
├── docs-claude/          # AI 向けコードベース資料 (このディレクトリ)
├── scripts/              # ビルドスクリプト (build-version.mjs)
├── assets/               # SVG マーカー
├── package.json
├── webpack.config.js     # メイン設定 (2 エントリ: embed / embed-core)
├── tsconfig.json
├── tsconfig.build.json
├── eslint.config.js
├── playwright.config.ts
├── vitest.config.ts
└── CLAUDE.md             # プロジェクトレベル指示 (Claude Code 用)
Add a custom footer
Add a custom sidebar

Clone this wiki locally