Monorepo Scaffold

Convert a single-app repository into a Turborepo + pnpm workspace monorepo, without breaking builds or release flow.

Purpose

• Standardize on pnpm workspaces + turbo

• Split runnable apps into apps/

• Move shared code and config into packages/

• Add reliable caching, fast CI, and clear ownership boundaries

Target Structure

Use this shape unless the repo already has stronger constraints.

. ├─ apps/ │ ├─ web/ │ ├─ mobile/ │ └─ api/ ├─ packages/ │ ├─ shared/ │ ├─ ui-web/ │ ├─ ui-mobile/ │ └─ config/ ├─ pnpm-workspace.yaml ├─ turbo.json └─ package.json

CLI Commands

Prefer explicit, reproducible commands.

Workspace baseline

pnpm add -D turbo pnpm install

Optional: scaffold common layout quickly

pnpm dlx create-turbo@latest --package-manager pnpm

Run tasks

pnpm turbo run build pnpm turbo run dev --filter=web pnpm turbo run test --continue

Workflow

Follow this order. Keep diffs small and reversible.

• Audit current scripts, build outputs, and deploy entrypoints.

• Create apps/ and packages/ folders.

• Move the existing app into apps/<name>/ with minimal edits.

• Add pnpm-workspace.yaml and include apps/* and packages/* .

• Add root turbo.json with a small, strict pipeline.

• Normalize scripts so each app/package exposes build , dev , lint , test , and typecheck when relevant.

• Extract shared code into packages/shared and wire via workspace deps.

• Extract shared config into packages/config and reference it explicitly.

• Update CI to run pnpm install then pnpm turbo run build lint test typecheck .

• Verify with targeted filters, then full pipeline.

Verification Checklist

Do not trust the migration until all checks pass.

• pnpm install completes without hoist hacks

• pnpm turbo run build succeeds from repo root

• pnpm turbo run dev --filter=<app> starts the expected app

• Each app builds from a clean checkout

• Shared packages are consumed via workspace:* ranges

• Outputs are declared in turbo.json for cache hits

• CI runs from root and matches local commands

References

• Setup guide: skills/monorepo-scaffold/references/turborepo-setup.md

• Migration checks: skills/monorepo-scaffold/references/migration-checklist.md