Home › Monorepos › Turborepo monorepo AGENTS.md

Turborepo monorepo AGENTS.md

AGENTS.md for pnpm + Turborepo 2 monorepos: workspace boundaries, filtered tasks, shared configs, and caching.

AGENTS.mdMonorepos

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# AGENTS.md: pnpm + Turborepo monorepo

## Layout
- `apps/*` are deployable apps; `packages/*` are shared libraries (`@repo/ui`, `@repo/db`, `@repo/config-*`).
- Each app or package may have its own `AGENTS.md` with local rules; the closest one wins.

## Commands
- Everything: `pnpm turbo run build lint test typecheck`
- One package and its deps: `pnpm turbo run test --filter=@repo/web...`
- Only what changed: `pnpm turbo run test --filter=...[origin/main]`
- Add a dependency to one package: `pnpm add zod --filter @repo/api` (never at the root unless it's tooling).

## Rules
- Packages import each other by package name (`@repo/ui`), declared in `package.json` with `"workspace:*"`. No relative imports across package folders.
- Apps never import from other apps. Shared code moves into a package.
- Each package exposes a public API via `exports` in `package.json`; don't deep-import internal files.
- Shared TS, ESLint and Tailwind config come from `packages/config-*`; extend them, don't copy.
- Tasks are defined in `turbo.json` with correct `dependsOn` (`^build`) and `outputs` so caching works. Env vars that affect output go in `env`.
- Keep one version of each external dependency across the repo (use pnpm catalogs if configured).

## Don't
- Don't run `pnpm install` with `--no-frozen-lockfile` in CI, or edit `pnpm-lock.yaml` by hand.

## Done
`pnpm turbo run lint typecheck test build --filter=...[origin/main]` passes.