Turborepo
Overview
Turborepo is a high-performance build system for JavaScript/TypeScript monorepos that intelligently caches task outputs, parallelizes execution across CPU cores, and ensures teams only rebuild what has changed. It integrates with npm, yarn, and pnpm workspaces.
Instructions
- When setting up a monorepo, define tasks in
turbo.json with dependsOn for ordering, use ^ prefix for topological dependencies (e.g., "dependsOn": ["^build"]), and specify outputs for cacheable artifacts.
- When configuring caching, define
outputs arrays for each task (["dist/**", ".next/**"]), list all build-affecting environment variables in env or globalEnv, and set up Remote Cache for cross-developer sharing.
- When filtering workspaces, use
--filter=@app/web to target specific packages, --filter=...[HEAD~1] for changed packages, and turbo run build --graph to visualize the dependency graph.
- When optimizing Docker builds, use
turbo prune --scope=@app/web to generate a minimal Docker context containing only the targeted package and its dependencies.
- When setting up CI/CD, enable Remote Cache for cross-PR cache sharing, use
--dry-run=json for pipeline analysis, and leverage incremental builds that only rebuild packages affected by PR changes.
- When organizing shared packages, create focused internal packages (
@repo/ui, @repo/db, @repo/auth) with shared tsconfig and ESLint configs.
Examples
Example 1: Set up a new Turborepo monorepo
User request: "Initialize a monorepo with a Next.js app and shared UI library"
Actions:
- Set up pnpm workspace with
apps/web and packages/ui directories
- Configure
turbo.json with build, dev, lint, and typecheck tasks
- Define task dependencies and cache outputs for each task
- Create shared
tsconfig base in packages/tsconfig
Output: A monorepo with parallel builds, intelligent caching, and shared configuration.
Example 2: Optimize Docker builds for deployment
User request: "Create a Dockerfile for deploying one service from our Turborepo monorepo"
Actions:
- Run
turbo prune --scope=@app/api to generate minimal context
- Create multi-stage Dockerfile using the pruned output
- Install dependencies and build only the targeted package
- Configure cache mounts for faster rebuilds
Output: A lean Docker image containing only the service and its dependencies, not the full monorepo.
Guidelines
- Always define
outputs for cacheable tasks; use empty outputs: [] for side-effect-only tasks like lint.
- List all environment variables in
env or globalEnv that affect build output.
- Use
^ prefix in dependsOn for tasks that consume dependency outputs (build, typecheck).
- Keep internal packages small and focused:
@repo/ui, @repo/db, @repo/auth.
- Use
turbo prune for Docker builds; never copy the entire monorepo into a container.
- Set up Remote Cache in CI for cross-developer and cross-PR cache sharing.
1---2name: turborepo3description: Assists with managing JavaScript/TypeScript monorepos using Turborepo. Use when configuring build pipelines, setting up caching, pruning workspaces for Docker, or optimizing CI/CD for monorepo projects. Trigger words: turborepo, turbo, monorepo, pipeline, workspace, remote cache, turbo.json.4license: Apache-2.05---67# Turborepo89## Overview1011Turborepo is a high-performance build system for JavaScript/TypeScript monorepos that intelligently caches task outputs, parallelizes execution across CPU cores, and ensures teams only rebuild what has changed. It integrates with npm, yarn, and pnpm workspaces.1213## Instructions1415- When setting up a monorepo, define tasks in `turbo.json` with `dependsOn` for ordering, use `^` prefix for topological dependencies (e.g., `"dependsOn": ["^build"]`), and specify `outputs` for cacheable artifacts.16- When configuring caching, define `outputs` arrays for each task (`["dist/**", ".next/**"]`), list all build-affecting environment variables in `env` or `globalEnv`, and set up Remote Cache for cross-developer sharing.17- When filtering workspaces, use `--filter=@app/web` to target specific packages, `--filter=...[HEAD~1]` for changed packages, and `turbo run build --graph` to visualize the dependency graph.18- When optimizing Docker builds, use `turbo prune --scope=@app/web` to generate a minimal Docker context containing only the targeted package and its dependencies.19- When setting up CI/CD, enable Remote Cache for cross-PR cache sharing, use `--dry-run=json` for pipeline analysis, and leverage incremental builds that only rebuild packages affected by PR changes.20- When organizing shared packages, create focused internal packages (`@repo/ui`, `@repo/db`, `@repo/auth`) with shared `tsconfig` and ESLint configs.2122## Examples2324### Example 1: Set up a new Turborepo monorepo2526**User request:** "Initialize a monorepo with a Next.js app and shared UI library"2728**Actions:**291. Set up pnpm workspace with `apps/web` and `packages/ui` directories302. Configure `turbo.json` with `build`, `dev`, `lint`, and `typecheck` tasks313. Define task dependencies and cache outputs for each task324. Create shared `tsconfig` base in `packages/tsconfig`3334**Output:** A monorepo with parallel builds, intelligent caching, and shared configuration.3536### Example 2: Optimize Docker builds for deployment3738**User request:** "Create a Dockerfile for deploying one service from our Turborepo monorepo"3940**Actions:**411. Run `turbo prune --scope=@app/api` to generate minimal context422. Create multi-stage Dockerfile using the pruned output433. Install dependencies and build only the targeted package444. Configure cache mounts for faster rebuilds4546**Output:** A lean Docker image containing only the service and its dependencies, not the full monorepo.4748## Guidelines4950- Always define `outputs` for cacheable tasks; use empty `outputs: []` for side-effect-only tasks like `lint`.51- List all environment variables in `env` or `globalEnv` that affect build output.52- Use `^` prefix in `dependsOn` for tasks that consume dependency outputs (build, typecheck).53- Keep internal packages small and focused: `@repo/ui`, `@repo/db`, `@repo/auth`.54- Use `turbo prune` for Docker builds; never copy the entire monorepo into a container.55- Set up Remote Cache in CI for cross-developer and cross-PR cache sharing.
eliferjunior