コンテンツにスキップ

開発ガイド

このページは、日常的な開発作業の入口をまとめたクイックガイドです。詳細な実装方針や Vendure 固有の深い説明は、個別の実装ドキュメントを参照してください。

最初に使うコマンド

  • just dev: 標準の統合起動。内部的には just dev-full を呼び出します。
  • just dev-services: PostgreSQL / Redis などの依存サービスを起動します。
  • just dev-vendure: Vendure Server を起動します。
  • just dev-storefront: Storefront を起動します。
  • just dev-dashboard: React Dashboard の開発サーバーを起動します。
  • just ports: Portless URL と内部ポート割り当てを確認します。
  • just dev-stop: 開発系プロセスをまとめて停止します。

初回セットアップ

  1. 依存関係をインストールする。
pnpm install
  1. 依存サービスを起動する。
just dev-services
  1. 型やドキュメント導線が大きく壊れていないことを確認する。
just typecheck
just docs-build

日常の開発フロー

統合起動 / 個別起動

# 標準の統合起動
just dev

# 個別起動
just dev-vendure
just dev-storefront
just dev-dashboard

# Portless URL の確認
just ports

just dev / just dev-vendure / just dev-storefront / just dev-dashboard は、 ローカル永続 DB の schema / seed catalog / runtime baseline drift を吸収するため、起動前に pnpm exec nx run ritsubi-vendure-server:migrate:run と pnpm exec nx run ritsubi-vendure-server:drift:sync:baseline を自動実行します。drift:sync:baseline は audit-driven に必要 repair だけを直列で実行します。pnpm run dev:services や package 単体コマンドではこの同期は走りません。

また just dev / just dev-full は dev_wp の local WordPress も起動し、install.php 状態や seed 欠落を検知した場合は wp-bootstrap / wp-bootstrap-verify 相当の修復を自動実行します。WordPress を個別起動する場合は引き続き just wp-up の後に just wp-bootstrap を使ってください。

Stack orchestration (process-compose)

just dev-full / just dev-storefront-stack / just dev-dashboard-stack / just dev-storefront-bypass の 4 種の stack 起動は process-compose で declarative にオーケストレーションされます。実体は process-compose.dev.yaml、エントリは scripts/dev/run-process-compose.sh <stack>。

  • 依存関係は process-compose の depends_on + readiness_probe で表現: Postgres ready → Vendure boot → Vendure healthy → Dashboard / Storefront 起動 → 全 UI healthy → URL バナー発火
  • Vendure の内側 HMR は apps/vendure-server/scripts/dev-vendure-watch.mjs が継続管理 (debounce + boot gate)。process-compose は外側の supervisor として TS / config の更新を待ち、子プロセスが死んだら availability.restart: on_failure で respawn します。
  • ログは tmp/dev-logs/<service>.log に集約。別ターミナルで process-compose attach -U (UDS 経由) を開けば TUI でサービスごとのログをタブ切替できます。
  • just dev-stop は process-compose stack を down → WordPress を down → PostgreSQL を down の順で完全停止します。stack の再起動 (Dev: Full 連打) では PostgreSQL コンテナを再利用し、docker compose down/up の往復は走りません。
  • mise tools に github:F1bonacc1/process-compose を pin しているので、mise install だけで配布されます。

GraphQL スキーマとコード生成

# Admin / Shop schema を packages/contract/schema へ出力
pnpm run schema:generate

# shared package の codegen
pnpm run codegen:shared

# Storefront 側の codegen
pnpm exec nx run ritsubi-storefront:codegen
  • packages/contract/generated/*.ts は codegen の tracked 正本です。
  • src/ 配下の *.js / *.d.ts / *.map は build artifact として扱い、commit 前に pnpm run lint:tracked-src-artifacts を通し、残骸があれば pnpm run clean:src-artifacts で掃除します。

Vendure の migration / seed

# ローカル migration 実行
pnpm exec nx run ritsubi-vendure-server:migrate:run

# migration 生成
pnpm exec nx run ritsubi-vendure-server:migrate:generate

# migration 巻き戻し
pnpm exec nx run ritsubi-vendure-server:migrate:revert

# ローカル seed
pnpm exec nx run ritsubi-vendure-server:db:seed:local

テストと品質確認

# ワークスペース全体
just lint
just typecheck
pnpm test

# src artifact の明示チェック / 掃除
pnpm run lint:tracked-src-artifacts
pnpm run clean:src-artifacts

# workspace build/test cache の掃除（.nx / .mkdocs/.uv-cache / app-local cache。node_modules も削除される）
pnpm run clean

# React Dashboard E2E
pnpm exec nx run ritsubi-vendure-dashboard-e2e:test:e2e

# Docs
just docs-build
just docs-spec

よく参照する詳細ガイド

補足

  • ルートからの操作は、原則として pnpm の直接実行より just を優先します。
  • 環境変数や secrets は just と AWS Secrets Manager の導線を前提にします。
  • Admin UI ではなく React Dashboard / Vendure Dashboard の用語を使います。