コンテンツにスキップ

開発・テスト用ポート体系（Issue #66）

  • 更新日: 2026-05-28
  • 更新者: Codex
  • 要約: 開発・テスト用 port の正本を packages/config/src/defaults.ts に統一し、 shell / process-compose 側は codegen された .env.defaults 経由で同じ値を読む。 Storefront 開発 port を 4301 に更新（Vite 移行後）。SSoT 構造と Portless / E2E の route 名ルールを追記。

目的

開発・テスト環境のポート割り当てを一覧化し、mock/E2E の規約案と代替案を比較できる状態にする。加えて、3000/4000番台の採否理由、before/after、影響範囲、動作確認手順、必須テスト（pass 条件）を明文化する。

Worktree 並列開発の運用

  • CLI の既定は Portless。URL は service.localhost を使う。
  • VS Code タスクの既定は localhost 固定ポート。
  • 初回のみ npm install -g portless@0.4.1 を実行する。
  • 分離単位は worktree（proxy port / state dir）。
  • 現在の値は just ports で確認できる。
  • 単体起動は CLI なら just dev-storefront / just dev-vendure / just dev-dashboard、VS Code なら just local-storefront / just local-vendure / just local-dashboard を使う。

プロセス運用と ports-env の組み合わせ方針

  • ローカル開発は just から直接起動（foreground）を基本とする。
  • dev-* は常に Portless、local-* は常に localhost 固定ポートで起動する。
  • 推奨入口（Vendure API）: just dev-vendure / just local-vendure
  • 推奨入口（Dashboard 単体）: just dev-dashboard / just local-dashboard
  • 推奨入口（Storefront）: just dev-storefront / just local-storefront
  • 推奨入口（統合起動、Dashboard 含む）: just dev-full / just local-full
  • 推奨入口（停止）: just dev-stop / just local-stop
  • 推奨入口（ポート確認）: just ports

情報源（SSOT）

一次情報（TS 定数）

開発・テスト用 port の 唯一の正本 は以下:

  • packages/config/src/defaults.ts — DEFAULT_STOREFRONT_PORT / DEFAULT_VENDURE_PORT / DEFAULT_DASHBOARD_DEV_PORT / DEFAULT_VENDURE_DEV_DB_PORT / DEFAULT_WORDPRESS_PORT / DEFAULT_PLAYWRIGHT_PORT / DEFAULT_PLAYWRIGHT_MOCK_PORT などを export。
  • TS は @ritsubi/config/defaults から型付き定数として import する。env.schema.ts の zod default()、runtime/index.ts の DEFAULTS、各種 URL builder は すべてこの constant を経由する。

二次情報（shell / 非 TS）

TS から直接 import できない consumer 向けに codegen で .env.defaults を生成し、 これを shell スクリプト / process-compose / nx project.json 等が読む:

  • .env.defaults — scripts/dev/codegen-env-defaults.mjs が defaults.ts から生成。手で編集しない (# AUTO-GENERATED 警告付き)。
  • scripts/dev/load-env-defaults.sh — bash から source して child process に export する helper。run-process-compose.sh / run-storefront.sh / run-vendure.sh で使われる。既に export 済みの env は 上書きしない (個別 override を尊重)。
  • scripts/dev/load-env-defaults.mjs — Node から process.env に流し込む helper。show-service-urls.mjs 等で使う。

Drift guard

  • pnpm run lint:env-defaults (= node scripts/dev/codegen-env-defaults.mjs --check) が .env.defaults と apps/storefront/lighthouserc.json の port 整合を検証する。
  • lefthook.yml の env-defaults-drift job が defaults.ts 編集時に同 check を実行。
  • 値変更時の手順: defaults.ts を編集 → pnpm run codegen:env-defaults で .env.defaults を再生成 → 手書き consumer (lighthouserc.json 等) を揃える。

参照 (port が現れる主な consumer)

  • 起動経路: apps/storefront/package.json, apps/storefront/project.json, apps/vendure-server/project.json, process-compose.dev.yaml
  • E2E: apps/storefront/playwright.e2e.shared.ts, apps/storefront/tests/e2e/global-setup.ts
  • 環境変数定義: apps/storefront/src/env.schema.ts, apps/vendure-server/.env.example
  • 例示: README.md, .env.example

現状ポート一覧（開発）

サービス 目的 ポート 環境変数 一次情報 (packages/config/src/defaults.ts)
Storefront (Vite - canonical) 開発サーバー 4301 STOREFRONT_PORT DEFAULT_STOREFRONT_PORT
Vendure API 開発サーバー 3021 VENDURE_PORT DEFAULT_VENDURE_PORT
Vendure Dashboard (Vite) 開発サーバー 6202 DASHBOARD_DEV_PORT DEFAULT_DASHBOARD_DEV_PORT
Vendure dev PostgreSQL host-side mapping 5433 VENDURE_DEV_DB_PORT DEFAULT_VENDURE_DEV_DB_PORT
WordPress (local) CMS ローカル 8181 WP_PORT / WP_HOME DEFAULT_WORDPRESS_PORT
Makeshop Dev Server 開発サーバー 8888 MAKESHOP_DEV_PORT (未集約 — .env.example 参照)

注: 上表は内部待受ポート（localhost / VS Code の既定値）。通常のアクセスは service.localhost:<worktree-proxy-port> を使う。

Portless URL 解決ルール（サーバーサイド）

  • Storefront のサーバーサイド fetch は、localhost / 127.0.0.1 / 0.0.0.0 / ::1 向け Vendure URL への初回アクセスが失敗した場合にだけ、同じ path と query を保ったまま Portless URL へ再試行する。
  • 再試行先の決定順序は以下のとおり。
  • PORTLESS_VENDURE_URL
  • PORTLESS_VENDURE_NAME + PORTLESS_PROXY_PORT（または PORTLESS_PORT）
  • 既定値 http://vendure.localhost:<proxyPort>
  • proxy port の決定順序は以下のとおり。
  • PORTLESS_PROXY_PORT / PORTLESS_PORT
  • worktree 名（.../worktrees/<id>）
  • Git ブランチ名
  • カレントディレクトリ名
  • 上記の識別子は slug 化したうえで、13000-16999 の範囲に決定的に割り当てる。
  • PORTLESS=0 の場合はこの再試行を行わない。

現状ポート一覧（E2E/テスト）

サービス 目的 ポート 環境変数/設定 一次情報 (packages/config/src/defaults.ts)
Storefront (E2E real) Playwright 実行用 4022 PLAYWRIGHT_PORT DEFAULT_PLAYWRIGHT_PORT
Storefront (E2E mock) Playwright (mock) 実行用 4032 PLAYWRIGHT_MOCK_PORT DEFAULT_PLAYWRIGHT_MOCK_PORT
Vendure API (E2E) Storefront/Dashboard E2E 連携 3022 PORT (未集約 — Playwright config 参照)

注: 通常開発の Vendure 本体は VENDURE_PORT、Playwright が自動起動する E2E 用 Vendure は PORT を使う。両者は別導線として扱う。 | Vendure Dashboard (E2E) | Playwright 実行用 | 5122 | DASHBOARD_DEV_PORT | apps/vendure-server/playwright.dashboard.config.ts, README.md |

原則: 通常開発の Vendure は 3021 を使い、3022 は Playwright / E2E の分離起動専用とする。注意: ローカルで 3021（通常開発）と 3022（E2E）を同時起動する場合、seed投入先とStorefront参照先がずれると検証が失敗しやすい。実データ確認時は VITE_PUBLIC_VENDURE_BASE_URL と VENDURE_BASE_URL を同一URLに固定すること。

Portless E2E の route 名

  • Storefront E2E の既定 route 名は storefront-e2e、Vendure E2E の既定 route 名は vendure-e2e。
  • route 名を変えたい場合は PORTLESS_STOREFRONT_E2E_NAME / PORTLESS_VENDURE_E2E_NAME を使う。
  • PLAYWRIGHT_SKIP_WEBSERVER=false（既定）かつ VENDURE_BASE_URL 未指定であれば、Playwright の global-setup も vendure-e2e.localhost:<worktree-proxy-port> を使う。
  • PLAYWRIGHT_SKIP_WEBSERVER=true で既存サーバーに接続する場合は、 PLAYWRIGHT_BASE_URL に加えて VENDURE_BASE_URL も明示指定して接続先を固定する。

mock/E2E 規約案の比較

案 概要 長所 短所
案A: 現状準拠 Storefront/Vendure は末尾1、E2E は末尾22。Dashboard は Vite デフォルト(開発) + 末尾22(E2E)を維持。 既存設定・テストと一致し変更が最小。 末尾1/末尾22の規則が全サービスで完全一致しない。
案B: 末尾1/末尾22の完全統一 すべての開発ポートを末尾1、E2E を末尾22 に統一する。 規則性が明確になり記憶しやすい。 Dashboard 開発ポートの変更が必要になり、関連設定・手順の見直しが発生。

3000/4000番台の採否理由

  • 3000番台: Vendure API が 3021/3022 を前提に設定されているため、バックエンドは 3000番台を採用する。
  • 4000番台: Storefront が 4001/4022 を前提に設定されているため、フロントは 4000番台を採用する。

before/after（今回の整合）

対象 Before After 根拠ファイル
Storefront E2E の例示ポート PLAYWRIGHT_PORT=4310 / PLAYWRIGHT_BASE_URL=http://127.0.0.1:4310 PLAYWRIGHT_PORT=4022 / PLAYWRIGHT_BASE_URL=http://127.0.0.1:4022 apps/storefront/.env.example, apps/storefront/.env.e2e.example
README の説明文 「4000番台のポートを使用」 表の内容に合わせた文言に変更 README.md

影響範囲と変更対象ファイル一覧

  • 変更対象
  • apps/storefront/.env.example
  • apps/storefront/.env.e2e.example
  • README.md
  • 参照先（SSOT/設定）
  • apps/storefront/playwright.config.ts
  • apps/vendure-server/playwright.dashboard.config.ts
  • apps/vendure-server/vite.config.mts
  • .env.example
  • apps/vendure-server/.env.example
  • apps/storefront/tests/e2e/README.md

変更後の動作確認手順と期待結果

  1. pnpm dev を実行する。
  2. 期待結果: Storefront が http://storefront.localhost:<worktree-proxy-port>、Vendure API が http://vendure.localhost:<worktree-proxy-port>/shop-api で利用できる。
  3. 期待結果: Dashboard のアクセスは http://dashboard.localhost:<worktree-proxy-port>/ でできる。
  4. 補足: Vite Dev Server は root 配信を正本とし、Vendure 経由では配信しない。
  5. Storefront E2E を実行する。
  6. 期待結果: Playwright の既定ベースURLが http://storefront-e2e.localhost:<worktree-proxy-port> で動作する。
  7. Vendure Dashboard E2E を実行する。
  8. 期待結果: Dashboard E2E（bundled 互換検証用）が http://vendure-e2e.localhost:<worktree-proxy-port>/dashboard を利用して動作する。
  9. 補足: これは独立起動 React Dashboard の正規経路ではない。

必須テストと pass 条件

  • Storefront E2E
  • コマンド: pnpm exec nx run ritsubi-storefront:test:e2e
  • pass 条件: Playwright が失敗なく完了する。
  • Vendure Dashboard E2E
  • コマンド: pnpm exec nx run ritsubi-vendure-dashboard-e2e:test:e2e
  • pass 条件: Playwright が失敗なく完了する。