Claude Code Monorepo Setup: Turborepo and Nx Guide

# Monorepo Configuration

## Workspace Structure
- `apps/` — deployable applications (web, api, mobile)
- `packages/` — shared libraries (ui, utils, config, types)
- `tooling/` — build config (eslint, tsconfig, jest presets)

## Package Manager
Use `pnpm` (not npm or yarn). Always run commands from the repo root.

## Build System
This repo uses Turborepo. Key commands:
- `pnpm turbo build` — build all packages
- `pnpm turbo build --filter=web` — build only `web` and its deps
- `pnpm turbo test --filter=...api` — test packages that depend on `api`
- `pnpm turbo lint` — lint all packages

## Adding Dependencies
- Workspace package: `pnpm add @repo/ui --filter=web`
- External package: `pnpm add zod --filter=api`
- Never run `npm install` or `yarn add`

## TypeScript
All packages extend `@repo/tsconfig`. Do not modify tsconfig directly in packages.

## Conventions
- New packages: copy `packages/_template/` and update `package.json`
- Shared types go in `packages/types/`, not in individual packages
- Never import across app boundaries (apps/ → apps/ is forbidden)

# UI Package

React component library. Components must:
- Be accessible (WCAG 2.1 AA)
- Export TypeScript types
- Have Storybook stories in `src/__stories__/`
- Use Tailwind CSS only — no inline styles

Do not import from other workspace packages except `@repo/types`.

# API Application

Express + Prisma REST API. Rules:
- All routes in `src/routes/`, one file per resource
- Use Zod for request validation
- Database access only through `src/db/` — never direct Prisma calls in routes
- Environment variables must be declared in `src/config.ts`

Build: `pnpm turbo build --filter=api`
Dev: `pnpm turbo dev --filter=api`
Test: `pnpm turbo test --filter=api`

## Turborepo Pipeline

Pipeline tasks defined in `turbo.json`:
- `build` — depends on upstream `^build`
- `test` — can run in parallel (no dependencies)
- `lint` — can run in parallel
- `dev` — persistent, run per-package

Filter syntax:
- `--filter=web` — only `web`
- `--filter=...web` — `web` and everything it depends on
- `--filter=web...` — `web` and everything that depends on it
- `--filter=[HEAD^1]` — only packages changed since last commit

claude "Add a Button component to packages/ui. After implementing, run pnpm turbo build --filter=ui to verify it builds."

## Nx Configuration

Project graph: `nx graph`
Key commands:
- `nx build api` — build the api project
- `nx test ui` — test the ui project
- `nx affected --target=build` — build only affected projects
- `nx run-many --target=lint --all` — lint all projects

Project types defined in `project.json` per package.
Generators: `nx g @nx/react:component Button --project=ui`

# Work in a specific package context
cd apps/web && claude "Add a new /dashboard route using the existing layout component"

# Cross-package work from root
claude "The Button component in packages/ui has a broken onClick type. Fix it and update all usages in apps/web and apps/mobile."

claude --add packages/ui/src/Button.tsx --add apps/web/src/pages/Dashboard.tsx \
  "Update Button to accept a loading prop and use it in Dashboard"

# Create isolated worktrees for parallel work
git worktree add ../repo-api-work main
git worktree add ../repo-web-work main

# Run agents in parallel (in separate terminals)
cd ../repo-api-work && claude "Add /users/preferences endpoint to apps/api"
cd ../repo-web-work && claude "Add user preferences page to apps/web"

json
// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [{
          "type": "command",
          "command": "pnpm turbo build --filter=$(git diff --name-only HEAD | head -1 | cut -d/ -f1-2) 2

---

## Frequently Asked Questions

### Does Claude Code understand Turborepo's `turbo.json` pipeline?
Not automatically. Add the key pipeline tasks and filter syntax to your root CLAUDE.md. Once documented, Claude uses the correct `--filter` flags and understands build dependencies when you ask it to make changes.

### How do I prevent Claude from modifying the wrong package?
Use per-package CLAUDE.md files with explicit scope boundaries ("Do not import from other workspace packages except X"). Additionally, run `claude` from within the target package directory, not the root, for package-specific tasks.

### Should I use one CLAUDE.md or many?
Both. Root CLAUDE.md defines workspace-wide rules (package manager, build system, conventions). Per-package CLAUDE.md files add package-specific context. Claude Code reads both when working in a subdirectory.

### How do parallel Claude Code agents work in a monorepo?
Use `git worktree add` to create isolated working trees from the same repo. Each worktree can have an independent Claude Code session editing different packages simultaneously without file conflicts.

### Can Claude Code run Turborepo commands automatically?
Yes, via hooks. Configure a `PostToolUse` hook in `.claude/settings.json` to run `pnpm turbo build --filter=<package>` after file edits. Claude sees the build output and can fix errors in the same session.

### What is the biggest mistake teams make with Claude Code in monorepos?
Using a single root-level CLAUDE.md without per-package files. This forces Claude to hold the entire workspace context in mind for every task, leading to cross-package mistakes. Per-package CLAUDE.md files dramatically improve accuracy.

### How do I handle private packages and internal tooling?
Add a `tooling/CLAUDE.md` that describes build config packages. Mark internal-only packages explicitly: "This package is a dev tooling preset — never import it in `apps/` or `packages/`."

## Related Guides

- [Claude Code Complete Guide](/claude-code-complete-guide) — Worktrees, hooks, CLAUDE.md, and parallel agents
- [Claude Agent SDK Guide](/claude-agent-sdk-guide) — Building automated agents for monorepo CI
- [Claude Code for Teams](/claude-code-team-setup) — Team-wide Claude Code configuration