playbooks

home / skills / phrazzld / claude-config / monorepo-scaffold

monorepo-scaffold skill

/skills/monorepo-scaffold

This skill helps transform a single-app repository into a Turborepo with pnpm workspaces, organizing apps and shared packages for faster builds.

npx playbooks add skill phrazzld/claude-config --skill monorepo-scaffold

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
2.5 KB
---
name: monorepo-scaffold
description: "Convert single-app repos into a Turborepo monorepo using pnpm workspaces. Use when splitting apps into apps/ and shared code into packages/ with cached pipelines."
effort: high
---

# 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.

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

## CLI Commands

Prefer explicit, reproducible commands.

```bash
# 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.

1. Audit current scripts, build outputs, and deploy entrypoints.
2. Create `apps/` and `packages/` folders.
3. Move the existing app into `apps/<name>/` with minimal edits.
4. Add `pnpm-workspace.yaml` and include `apps/*` and `packages/*`.
5. Add root `turbo.json` with a small, strict pipeline.
6. Normalize scripts so each app/package exposes `build`, `dev`, `lint`, `test`, and `typecheck` when relevant.
7. Extract shared code into `packages/shared` and wire via workspace deps.
8. Extract shared config into `packages/config` and reference it explicitly.
9. Update CI to run `pnpm install` then `pnpm turbo run build lint test typecheck`.
10. 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`

Overview

This skill converts a single-app repository into a Turborepo monorepo using pnpm workspaces, preserving builds and release flows. It reorganizes runnable apps into apps/ and shared code/config into packages/, and adds a strict Turbo pipeline for reliable caching and faster CI. The goal is minimal, reversible diffs and clear ownership boundaries.

How this skill works

The skill provides a reproducible migration workflow: audit scripts and outputs, create apps/ and packages/, move the existing app with minimal edits, and register all workspaces in pnpm-workspace.yaml. It adds a root turbo.json pipeline, normalizes per-package scripts (build, dev, lint, test, typecheck), and wires shared packages using workspace:* ranges so Turbo can cache and run tasks across the repo. It includes verification steps and CI changes to validate the migration.

When to use it

  • You have a single-app repo and want to split into multiple apps with shared packages.
  • You need consistent build caching and faster CI across projects.
  • You want to migrate to pnpm workspaces and Turbo without disrupting releases.
  • You need clearer ownership of app vs shared code and consistent scripts.
  • You plan to add more apps or reuse shared libraries in future.

Best practices

  • Keep changes small and reversible: move one app and validate before proceeding.
  • Normalize scripts so each workspace exposes build/dev/lint/test/typecheck as applicable.
  • Declare outputs in turbo.json to maximize cache hits and reproducible builds.
  • Use workspace:* ranges when consuming local packages to enable atomic upgrades and correct linking.
  • Update CI to run from the repo root: pnpm install then pnpm turbo run build lint test typecheck.

Example use cases

  • Split a web frontend and an API into apps/web and apps/api while extracting shared utilities to packages/shared.
  • Migrate a mobile app into apps/mobile and extract UI primitives into packages/ui-mobile for reuse.
  • Introduce a centralized packages/config to share ESLint, Jest, and build configs across apps.
  • Speed up CI by leveraging turbo.json cached pipelines and running fewer full builds on incremental changes.
  • Onboard multiple teams by clarifying ownership boundaries between apps/ and packages/.

FAQ

Will this change break existing deployments?

If you follow the migration steps and verify builds from a clean checkout, deployments should remain unchanged because deploy entrypoints and build outputs are preserved; adjust CI to run root-level commands.

How do I ensure Turbo cache hits?

Declare outputs for each task in turbo.json and keep deterministic build outputs; use workspace:* deps and consistent scripts so Turbo can track inputs and reuse cached artifacts.