pnpm workspaces でモノレポ化

[badmintoncryer]

概要

リポジトリ全体を pnpm workspaces によるモノレポ構成に再構築し、以下の構成に分離する。

+-- apps/
|   +-- cdk/                  # AWS CDK インフラ
|   +-- webapp/               # Next.js アプリ
|   +-- async-job/            # 非同期ジョブハンドラー
|   `-- migration-runner/     # DB マイグレーション
`-- packages/
    +-- db/                   # Prisma スキーマ・クライアント
    `-- shared-types/         # 共有型定義

v3ロードマップにて触れられている内容

背景・動機

現在、Next.js アプリと非同期ジョブハンドラーは単一の webapp/ パッケージに同居しているが、ビルド・デプロイは別々のアーティファクトとして行われている：

• Dockerfile → Next.js Lambda（next build の standalone 出力）
• job.Dockerfile → ジョブハンドラー Lambda + マイグレーション Lambda（esbuild で src/jobs/*.ts をバンドル）

これにより以下の問題が生じている：

• 依存関係の肥大化: ジョブハンドラーの Docker イメージビルド時に npm ci で Next.js / React 等の不要な依存もすべてインストールされる
• 単一 package.json: デプロイターゲットごとに依存関係を独立管理できない
• migration Lambda の混在: DB マイグレーション用の migration-runner.ts が job.Dockerfile で非同期ジョブと一緒にバンドルされている。migration runner は Prisma の db push を実行するだけのインフラ寄りの処理であり、ビジネスロジックである非同期ジョブとは責務が異なるが、同一イメージに同梱されている

提案する構成

apps/

パッケージ	内容	現在の場所
apps/cdk	AWS CDK インフラコード	cdk/
apps/webapp	Next.js アプリ（UI + Server Actions）	webapp/src/app/, components/, hooks/
apps/async-job	非同期ジョブハンドラー	webapp/src/jobs/async-job-runner.ts, async-job/
apps/migration-runner	DB マイグレーション	webapp/src/jobs/migration-runner.ts

packages/

パッケージ	内容	現在の場所
packages/db	Prisma スキーマ・クライアント・マイグレーションファイル・Zod 生成型	webapp/prisma/, webapp/src/lib/prisma.ts, webapp/src/lib/generated/
packages/shared-types	ジョブペイロード型、共有ユーティリティ（events, auth 等）	webapp/src/lib/

依存関係の方向

apps/webapp  ──→  packages/shared-types  ←──  apps/async-job
                          │
                    packages/db
                          ↑
                  apps/migration-runner

apps/cdk は他のパッケージに直接依存しない（Docker ビルドパスのみ参照）

• packages/db: prisma、@prisma/client、zod に依存
• packages/shared-types: packages/db、@aws-sdk/*（events/auth）に依存
• apps/webapp: packages/shared-types、packages/db、react、next、aws-amplify、UI ライブラリに依存
• apps/async-job: packages/shared-types、packages/db、@aws-sdk/client-translate に依存
• apps/migration-runner: packages/db に依存
• アプリ同士は相互に依存しない

共有型の整理

現在 webapp/src/lib/jobs.ts が @/jobs/async-job-runner から JobPayloadProps をインポートしてジョブ呼び出しの型安全性を確保している。分離後は：

• JobPayloadProps 型とペイロードスキーマを packages/shared-types に移動し、apps/webapp と apps/async-job の両方から参照可能にする
• apps/webapp は Lambda 呼び出し時の型として使用、apps/async-job は受信イベントのバリデーションに使用

技術的アプローチ

pnpm Workspaces

pnpm-workspace.yaml でモノレポを定義：

packages:
  - "apps/*"
  - "packages/*"

内部依存は workspace:* プロトコルで解決：

// apps/webapp/package.json
{ "dependencies": { "@webapp/shared-types": "workspace:*", "@webapp/db": "workspace:*" } }

// apps/async-job/package.json
{ "dependencies": { "@webapp/shared-types": "workspace:*", "@webapp/db": "workspace:*" } }

// apps/migration-runner/package.json
{ "dependencies": { "@webapp/db": "workspace:*" } }

// packages/shared-types/package.json
{ "dependencies": { "@webapp/db": "workspace:*" } }

[konokenj]

補足: 実プロジェクトでの移行経験から

2つの実プロジェクトでnpm → pnpm workspaces移行を実施した経験から、いくつか補足します。

1. なぜnpm workspacesではなくpnpm workspacesか

• pnpm deploy --filter: workspace依存を解決したself-containedなディレクトリを生成できる。npmにはこの機能がない。モノレポ + Dockerビルドの組み合わせで、これがないとDockerfile内でのworkspace依存解決が非常に煩雑になる
• Phantom dependency防止: pnpmの厳密な依存解決により、package.jsonに宣言していないパッケージを暗黙的にimportできない。テンプレートとしてコピーした後の依存管理が健全になる
• 統合lockfile + ディスク効率: content-addressable storageによる重複排除。4つのpackage-lock.jsonが1つのpnpm-lock.yamlに統合される

特にpnpm deployはDockerビルドで以下のように使えます:

FROM node:22-slim AS base
RUN corepack enable && corepack prepare pnpm@latest --activate

FROM base AS deps
WORKDIR /build
COPY pnpm-lock.yaml pnpm-workspace.yaml package.json ./
COPY apps/webapp/package.json apps/webapp/
COPY packages/db/package.json packages/db/
COPY packages/shared-types/package.json packages/shared-types/
RUN pnpm install --frozen-lockfile

FROM base AS builder
WORKDIR /build
COPY --from=deps /build .
COPY apps/webapp/ apps/webapp/
COPY packages/db/ packages/db/
COPY packages/shared-types/ packages/shared-types/
RUN pnpm deploy --filter=webapp --prod /app
WORKDIR /app
RUN pnpm run build

pnpm deployがフラット化したディレクトリを生成するため、Next.jsのoutputFileTracingRoot設定は不要です（検証済み）。

2. CDK NodejsFunctionとの統合（実装時の注意事項）

v3ではasync-jobのNodejsFunction化が検討されています（Discussion #94 提案1）。pnpm monorepoでNodejsFunctionを使う場合、以下の点に注意が必要です:

• esbuildはルートのdevDependenciesに配置必須: NodejsFunctionはルートのnode_modules/esbuildを探す。サブパッケージに配置すると警告なしにDockerバンドリングにフォールバックし、ビルドが急に遅くなる（エラーが出ないため気づきにくい）
• depsLockFilePathの明示指定が必須: 指定しないとNodejsFunctionがpackage-lock.jsonを探してnpmと判定し、バンドリングが失敗する
• workspace依存のバンドル: externalModules: []（全バンドル）方式であれば、esbuildがpnpmのsymlinkを正常に辿り、共有パッケージのコードがバンドルに含まれる（検証済み）

new NodejsFunction(this, 'Handler', {
  entry: join(__dirname, '../..', '../', 'apps', 'async-job', 'index.ts'),
  depsLockFilePath: join(__dirname, '../..', '../', 'pnpm-lock.yaml'),
  bundling: { externalModules: [] },
});

3. .dockerignoreのモノレポ対応

ビルドコンテキストがモノレポルートに変わるため、.dockerignoreをルートに配置する必要があります。CDK側ではContainerImageBuildのdirectoryとexcludeを更新:

new ContainerImageBuild(this, 'Build', {
  directory: '..',  // モノレポルート
  file: 'apps/webapp/Dockerfile',
  ignoreMode: IgnoreMode.DOCKER,
  exclude: parseDockerignore('../.dockerignore'),
});

4. onlyBuiltDependenciesの設定

pnpm v9+ではネイティブバイナリを含むパッケージのpostinstallスクリプトがデフォルトで実行されません。pnpm-workspace.yamlに明示が必要です:

packages:
  - "apps/*"
  - "packages/*"

onlyBuiltDependencies:
  - esbuild

v3でPrisma → Drizzle移行が予定されているため、Prisma関連のエントリは不要になりますが、esbuild（CDK NodejsFunction用）は必要です。ユーザーが画像最適化でsharpを追加した場合はここに追記が必要になります。