Agent instructionsScan: pass
Turborepo Monorepo CLAUDE.md
Root CLAUDE.md for a Turborepo + pnpm workspace with apps/ and packages/, filtered commands, shared-code placement, changesets, and nested CLAUDE.md files.
Add a trust badge to your README
[](https://waxmark.app/items/monorepo-turborepo-claude-md/scan)
# {{PROJECT_NAME}} monorepo
Turborepo 2.x + pnpm workspaces. Package manager is **pnpm** (version pinned in `packageManager` in the root `package.json`); never use npm or yarn. Workspace globs in `pnpm-workspace.yaml`: `apps/*`, `packages/*`.
## Map
| Path | Package name | What it is |
|------|--------------|------------|
| `apps/{{WEB_APP}}` | `@{{SCOPE}}/{{WEB_APP}}` | Web app (deployable) |
| `apps/{{API_APP}}` | `@{{SCOPE}}/{{API_APP}}` | API service (deployable) |
| `packages/ui` | `@{{SCOPE}}/ui` | Shared React components |
| `packages/db` | `@{{SCOPE}}/db` | Schema, migrations, DB client |
| `packages/config` | `@{{SCOPE}}/config` | Shared `tsconfig`, ESLint, Prettier configs |
Each package has its own `CLAUDE.md` with package-specific rules. Read it before editing files there; Claude Code loads it automatically the first time you read or edit a file in that directory.
## Commands (run from the repo root)
| Task | Command |
|------|---------|
| Install | `pnpm install --frozen-lockfile` |
| Everything | `pnpm turbo run build lint typecheck test` |
| One package | `pnpm turbo run test --filter=@{{SCOPE}}/ui` |
| A package and its dependents | `pnpm turbo run build --filter=...@{{SCOPE}}/ui` |
| Only what changed vs main | `pnpm turbo run test --filter='...[origin/main]'` |
| Dev server for one app | `pnpm --filter @{{SCOPE}}/{{WEB_APP}} dev` |
| Add a dependency to one package | `pnpm add <pkg> --filter @{{SCOPE}}/{{WEB_APP}}` |
| Add an internal package as a dependency | `pnpm add @{{SCOPE}}/ui@workspace:* --filter @{{SCOPE}}/{{WEB_APP}}` |
| Record a release note | `pnpm changeset` |
Definition of done: `pnpm turbo run lint typecheck test --filter='...[origin/main]'` exits 0, and a changeset exists if you changed a published package. Paste the turbo summary (`Tasks: N successful, N total`).
## Where code goes
- Used by one app only: inside that app. Do not create a package for a single consumer.
- Used by two or more apps: `packages/<name>`. Export through the `exports` field in its `package.json`; consumers import `@{{SCOPE}}/<name>`, never a relative path across package boundaries.
- Types shared between `{{API_APP}}` and `{{WEB_APP}}`: `packages/types`. Zod schemas there, inferred types exported alongside.
- Config (`tsconfig`, ESLint, Prettier): `packages/config`. Apps extend it; do not copy config files between packages.
## Workspace rules
- Internal dependencies use `"workspace:*"`. Never a version range for an internal package.
- Every package has `build`, `lint`, `typecheck`, and `test` scripts, even if a script is a no-op `echo`, so `turbo run` filters stay uniform.
- Task graph lives in `turbo.json`. If a task reads files outside its package, add them to `inputs`; if it writes files, add them to `outputs`. Do not set `"cache": false` to make a flaky task pass.
- Env vars a task depends on go in `turbo.json` `env` (or `globalEnv`), otherwise the cache will serve stale output.
- Node version from `.nvmrc`. TypeScript version is a single root devDependency; packages do not pin their own.
## Changesets
- Any change to a package under `packages/` that consumers can observe needs `pnpm changeset` run and the generated `.changeset/*.md` committed with the change.
- Pick `patch` for fixes, `minor` for additive API, `major` for breaking. Apps in `apps/` are `"ignore"`d in `.changeset/config.json` and never get changesets.
- Do not run `pnpm changeset version` or `pnpm changeset publish`; CI does that on main.
## Nested CLAUDE.md files
- Each `apps/*` and `packages/*` directory has a `CLAUDE.md` with only what is specific to it: its own commands, its layout, its gotchas. Nothing in a nested file should repeat this root file.
- Nested files load on demand, the first time a file in that directory is read, written, or edited, and they are appended after this one, so they can tighten but should not contradict root rules.
- When you learn something about a package that future sessions need, add it to that package's `CLAUDE.md`, not here.
- Rules that apply to a file type everywhere (for example all `*.test.ts`) go in `.claude/rules/<topic>.md` with a `paths:` frontmatter instead of being repeated in every package.
## Do not
- Do not import from another package's `src/`; use its public entry point.
- Do not run `pnpm install` inside a package directory; always from the root.
- Do not edit `pnpm-lock.yaml` by hand or delete it to fix a conflict; run `pnpm install` and commit the result.
- Do not add a root-level dependency that only one package uses.