Update to Vercel

{
  "name": "turborepo",
  "description": "Turborepo expert guidance. Use when setting up or optimizing monorepo builds, configuring task caching, remote caching, parallel execution, or the --affected flag for incremental CI.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 88
    }
  ],
  "skill_md_contents": "---\nname: turborepo\ndescription: Turborepo expert guidance. Use when setting up or optimizing monorepo builds, configuring task caching, remote caching, parallel execution, or the --affected flag for incremental CI.\nmetadata:\n  priority: 5\n  docs:\n    - \"https://turborepo.dev/docs\"\n  sitemap: \"https://turborepo.dev/sitemap.xml\"\n  pathPatterns: \n    - 'turbo.json'\n    - 'turbo/**'\n  bashPatterns: \n    - '\\bturbo\\s+(run|build|test|lint|dev)\\b'\n    - '\\bnpx\\s+turbo\\b'\n    - '\\bbunx\\s+turbo\\b'\n---\n\n# Turborepo\n\nYou are an expert in Turborepo v2.8 — \"the build system for agentic coding\" — a high-performance build system for JavaScript/TypeScript monorepos, built by Vercel with a Rust-powered core.\n\n## Key Features\n\n- **Task caching**: Content-aware hashing — only rebuilds when files actually change\n- **Remote caching**: Share build caches across machines and CI via Vercel\n- **Parallel execution**: Uses all CPU cores automatically\n- **Incremental builds**: `--affected` flag runs only changed packages + dependents\n- **Pruned subsets**: Generate minimal monorepo for deploying a single app\n- **Dependency graph awareness**: Understands package relationships\n- **Git worktree cache sharing**: Automatically shares local cache across worktrees (2.8+)\n- **Devtools**: Visual package and task graph explorer via `turbo devtools` (2.8+)\n- **Composable configuration**: Extend `turbo.json` from any package, not just root (2.7+)\n- **AI-enabled docs**: `turbo docs` returns markdown responses optimized for AI agents (2.8+)\n\n## Setup\n\n```bash\nnpx create-turbo@latest\n# or add to existing monorepo:\nnpm install turbo --save-dev\n# upgrade existing Turborepo:\nnpx @turbo/codemod migrate\n```\n\n## turbo.json Task Pipeline\n\nThe `turbo.json` file defines your task dependency graph. Here are comprehensive examples:\n\n### Basic pipeline\n\n```json\n{\n  \"$schema\": \"https://turborepo.dev/schema.json\",\n  \"tasks\": {\n    \"build\": {\n      \"description\": \"Compile TypeScript and bundle the application\",\n      \"dependsOn\": [\"^build\"],\n      \"outputs\": [\".next/**\", \"dist/**\"]\n    },\n    \"test\": {\n      \"description\": \"Run the test suite\",\n      \"dependsOn\": [\"build\"]\n    },\n    \"lint\": {\n      \"description\": \"Lint source files\"\n    },\n    \"dev\": {\n      \"cache\": false,\n      \"persistent\": true\n    }\n  }\n}\n```\n\n### Advanced pipeline with environment variables and inputs\n\n```json\n{\n  \"$schema\": \"https://turborepo.dev/schema.json\",\n  \"globalDependencies\": [\".env\"],\n  \"globalEnv\": [\"CI\", \"NODE_ENV\"],\n  \"tasks\": {\n    \"build\": {\n      \"dependsOn\": [\"^build\"],\n      \"outputs\": [\".next/**\", \"dist/**\"],\n      \"env\": [\"DATABASE_URL\", \"NEXT_PUBLIC_API_URL\"],\n      \"inputs\": [\"src/**\", \"package.json\", \"tsconfig.json\"]\n    },\n    \"test\": {\n      \"dependsOn\": [\"build\"],\n      \"outputs\": [\"coverage/**\"],\n      \"env\": [\"TEST_DATABASE_URL\"]\n    },\n    \"test:unit\": {\n      \"dependsOn\": [],\n      \"outputs\": [\"coverage/**\"]\n    },\n    \"lint\": {\n      \"inputs\": [\"src/**\", \".eslintrc.*\"]\n    },\n    \"typecheck\": {\n      \"dependsOn\": [\"^build\"],\n      \"inputs\": [\"src/**\", \"tsconfig.json\"]\n    },\n    \"db:generate\": {\n      \"cache\": false\n    },\n    \"dev\": {\n      \"cache\": false,\n      \"persistent\": true\n    },\n    \"clean\": {\n      \"cache\": false\n    }\n  }\n}\n```\n\n### Key Configuration\n\n- `dependsOn: [\"^build\"]` — Run `build` in dependencies first (`^` = topological)\n- `dependsOn: [\"build\"]` — Run `build` in the same package first (no `^`)\n- `outputs` — Files to cache (build artifacts)\n- `inputs` — Files that affect the task hash (default: all non-gitignored files)\n- `env` — Environment variables that affect the task hash\n- `cache: false` — Skip caching (for dev servers, codegen)\n- `persistent: true` — Long-running tasks (dev servers)\n- `globalDependencies` — Files that invalidate all task caches when changed\n- `globalEnv` — Env vars that invalidate all task caches when changed\n\n## Workspace Filtering\n\nRun tasks in specific packages or subsets of your monorepo:\n\n```bash\n# Single package\nturbo build --filter=web\n\n# Package and its dependencies\nturbo build --filter=web...\n\n# Package and its dependents (what depends on it)\nturbo build --filter=...ui\n\n# Multiple packages\nturbo build --filter=web --filter=api\n\n# By directory\nturbo build --filter=./apps/*\n\n# Packages that changed since main\nturbo build --filter=[main]\n\n# Combine: changed packages and their dependents\nturbo build --filter=...[main]\n\n# Exclude a package\nturbo build --filter=!docs\n\n# Packages matching a pattern\nturbo build --filter=@myorg/*\n```\n\n### Filter syntax reference\n\n| Pattern | Meaning |\n|---------|---------|\n| `web` | Only the `web` package |\n| `web...` | `web` and all its dependencies |\n| `...web` | `web` and all its dependents |\n| `...web...` | `web`, its dependencies, and its dependents |\n| `./apps/*` | All packages in the `apps/` directory |\n| `[main]` | Packages changed since `main` branch |\n| `{./apps/web}[main]` | `web` only if it changed since `main` |\n| `!docs` | Exclude the `docs` package |\n\n## CI Matrix Strategies\n\n### GitHub Actions — parallel jobs per package\n\n```yaml\nname: CI\non: [push, pull_request]\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0 # Required for --affected\n      - uses: actions/setup-node@v4\n        with:\n          node-version: 22\n      - run: npm ci\n      - run: turbo build test lint --affected\n        env:\n          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}\n          TURBO_TEAM: ${{ vars.TURBO_TEAM }}\n\n  deploy-web:\n    needs: build\n    if: github.ref == 'refs/heads/main'\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - run: npm ci\n      - run: turbo build --filter=web\n        env:\n          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}\n          TURBO_TEAM: ${{ vars.TURBO_TEAM }}\n```\n\n### Dynamic matrix from workspace list\n\n```yaml\njobs:\n  detect:\n    runs-on: ubuntu-latest\n    outputs:\n      packages: ${{ steps.list.outputs.packages }}\n    steps:\n      - uses: actions/checkout@v4\n      - id: list\n        run: |\n          PACKAGES=$(turbo ls --affected --output=json | jq -c '[.[].name]')\n          echo \"packages=$PACKAGES\" >> \"$GITHUB_OUTPUT\"\n\n  test:\n    needs: detect\n    if: needs.detect.outputs.packages != '[]'\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        package: ${{ fromJson(needs.detect.outputs.packages) }}\n    steps:\n      - uses: actions/checkout@v4\n      - run: npm ci\n      - run: turbo test --filter=${{ matrix.package }}\n```\n\n### Remote caching in CI\n\n```bash\n# Set in CI environment\nTURBO_TOKEN=your-vercel-token\nTURBO_TEAM=your-vercel-team\n\n# Builds automatically use remote cache\nturbo build\n```\n\n## Watch Mode\n\nRun tasks in watch mode for development — re-executes when source files change:\n\n```bash\n# Watch a specific task\nturbo watch test\n\n# Watch with a filter\nturbo watch test --filter=web\n\n# Watch multiple tasks\nturbo watch test lint\n```\n\nWatch mode respects the task graph — if `test` depends on `build`, changing a source file re-runs `build` first, then `test`.\n\n### Persistent tasks vs watch\n\n- `persistent: true` in turbo.json: The task itself is long-running (e.g., `next dev`). Turbo starts it and keeps it alive.\n- `turbo watch`: Turbo re-invokes the task on file changes. Use for tasks that run and exit (e.g., `vitest run`, `tsc --noEmit`).\n\n## Boundary Rules\n\nEnforce architectural constraints across your monorepo with `boundaries` in turbo.json:\n\n```json\n{\n  \"boundaries\": {\n    \"tags\": {\n      \"apps/*\": [\"app\"],\n      \"packages/ui\": [\"shared\", \"ui\"],\n      \"packages/utils\": [\"shared\"],\n      \"packages/config\": [\"config\"]\n    },\n    \"rules\": [\n      {\n        \"from\": [\"app\"],\n        \"allow\": [\"shared\"]\n      },\n      {\n        \"from\": [\"shared\"],\n        \"deny\": [\"app\"]\n      }\n    ]\n  }\n}\n```\n\nThis enforces:\n- Apps can import shared packages\n- Shared packages cannot import from apps\n- Violations produce build-time errors with `turbo boundaries`\n\n```bash\n# Check boundary compliance\nturbo boundaries\n\n# Add to your pipeline\n{\n  \"tasks\": {\n    \"check\": {\n      \"dependsOn\": [\"lint\", \"typecheck\", \"boundaries\"]\n    },\n    \"boundaries\": {}\n  }\n}\n```\n\n## Graph Visualization\n\nInspect your task dependency graph:\n\n```bash\n# Print graph to terminal\nturbo build --graph\n\n# Output as DOT format (Graphviz)\nturbo build --graph=graph.dot\n\n# Output as JSON\nturbo build --graph=graph.json\n\n# Open interactive graph in browser\nturbo build --graph=graph.html\n```\n\n### Dry run — see what would execute\n\n```bash\n# Show tasks that would run without executing them\nturbo build --dry-run\n\n# JSON output for programmatic use\nturbo build --dry-run=json\n```\n\nThe dry run output shows:\n- Each task that would execute\n- Cache status (HIT or MISS)\n- Dependencies and dependents\n- File hash used for caching\n\n## Devtools & Docs (2.8+)\n\n```bash\n# Visual package/task graph explorer (hot-reloads on changes)\nturbo devtools\n\n# Search Turborepo docs from the terminal (returns agent-friendly markdown)\nturbo docs\n\n# Upgrade to latest Turborepo\nnpx @turbo/codemod migrate\n```\n\n> **Note**: `turbo docs` output is optimized for AI coding agents — markdown format preserves context windows. The docs site also includes sample prompts for common tasks you can copy directly into your agent.\n\n## Composable Configuration (2.7+)\n\nPackage configs can now extend from any workspace package, not just the root:\n\n```json\n// packages/ui/turbo.json\n{\n  \"extends\": [\"@myorg/config\"],\n  \"tasks\": {\n    \"build\": {\n      \"outputs\": [\"dist/**\"]\n    }\n  }\n}\n```\n\n## Common Commands\n\n```bash\n# Run build across all packages\nturbo build\n\n# Run only affected packages (changed since main branch)\nturbo build --affected\n\n# Run specific tasks in specific packages\nturbo build --filter=web\n\n# Run with remote caching\nturbo build --remote-cache\n\n# Prune monorepo for a single app deployment\nturbo prune web --docker\n\n# List all packages\nturbo ls\n\n# List affected packages\nturbo ls --affected\n```\n\n## Remote Caching\n\n```bash\n# Login to Vercel for remote caching\nturbo login\n\n# Link to a Vercel team\nturbo link\n\n# Now builds share cache across all machines\nturbo build  # Cache hits from CI, teammates, etc.\n```\n\n## Monorepo Structure\n\n```\nmy-monorepo/\n├── turbo.json\n├── package.json\n├── apps/\n│   ├── web/           # Next.js app\n│   │   └── package.json\n│   ├── api/           # Backend service\n│   │   └── package.json\n│   └── docs/          # Documentation site\n│       └── package.json\n├── packages/\n│   ├── ui/            # Shared component library\n│   │   └── package.json\n│   ├── config/        # Shared configs (eslint, tsconfig)\n│   │   └── package.json\n│   └── utils/         # Shared utilities\n│       └── package.json\n└── node_modules/\n```\n\n## --affected Flag\n\nThe most important optimization for CI pipelines:\n\n```bash\n# Only build/test packages that changed since main\nturbo build test lint --affected\n```\n\nThis performs intelligent graph traversal:\n1. Identifies changed files since the base branch\n2. Maps changes to affected packages\n3. Includes all dependent packages (transitively)\n4. Runs tasks only for the affected subgraph\n\n## Microfrontends & Multi-App Composition\n\nTurborepo is the recommended orchestration layer for Vercel's Microfrontends architecture — composing multiple independently-deployed apps behind a single URL.\n\n### Monorepo Structure for Microfrontends\n\n```\nmy-platform/\n├── turbo.json\n├── package.json\n├── apps/\n│   ├── shell/          # Layout / shell app (owns top-level routing)\n│   ├── dashboard/      # Micro-app: dashboard features\n│   ├── settings/       # Micro-app: settings features\n│   └── marketing/      # Micro-app: public marketing site\n└── packages/\n    ├── ui/             # Shared component library\n    ├── auth/           # Shared auth utilities\n    └── config/         # Shared tsconfig, eslint\n```\n\n### Independent Deploys\n\nEach micro-app is a separate Vercel project with its own build and deploy lifecycle:\n\n```bash\n# Deploy only the dashboard micro-app\nturbo build --filter=dashboard\n\n# Deploy all micro-apps in parallel\nturbo build --filter=./apps/*\n\n# Deploy only micro-apps that changed since main\nturbo build --filter=./apps/*...[main]\n```\n\n### Shared Packages Across Micro-Apps\n\nUse Turborepo's dependency graph to share code without coupling deploys:\n\n```json\n{\n  \"tasks\": {\n    \"build\": {\n      \"dependsOn\": [\"^build\"],\n      \"outputs\": [\".next/**\", \"dist/**\"]\n    }\n  }\n}\n```\n\nShared packages (`ui`, `auth`, `config`) are built first via `^build`, then each micro-app builds against the latest shared code. Remote caching ensures shared package builds are never repeated across micro-app deploys.\n\n### Multi-Zone Patterns\n\nNext.js multi-zones let each micro-app own a URL path prefix while sharing a single domain:\n\n```ts\n// apps/shell/next.config.ts\nimport type { NextConfig } from 'next'\n\nconst nextConfig: NextConfig = {\n  async rewrites() {\n    return [\n      { source: '/dashboard/:path*', destination: 'https://dashboard.example.com/dashboard/:path*' },\n      { source: '/settings/:path*', destination: 'https://settings.example.com/settings/:path*' },\n    ]\n  },\n}\n\nexport default nextConfig\n```\n\nCombine with Turborepo boundary rules to enforce architectural isolation:\n\n```json\n{\n  \"boundaries\": {\n    \"tags\": {\n      \"apps/*\": [\"micro-app\"],\n      \"packages/ui\": [\"shared\"],\n      \"packages/auth\": [\"shared\"]\n    },\n    \"rules\": [\n      { \"from\": [\"micro-app\"], \"allow\": [\"shared\"] },\n      { \"from\": [\"shared\"], \"deny\": [\"micro-app\"] }\n    ]\n  }\n}\n```\n\n### When to Use Turborepo for Microfrontends\n\n| Scenario | Recommended? |\n|----------|-------------|\n| Multiple teams owning independent features | Yes — independent deploys + shared packages |\n| Single team, single app | No — standard Next.js is simpler |\n| Shared component library across apps | Yes — `packages/ui` with boundary rules |\n| Gradual migration from monolith | Yes — extract features into micro-apps incrementally |\n| Need version-skew protection | Yes — isolated builds per micro-app |\n\n### Related Documentation\n\n- [Vercel Microfrontends](https://vercel.com/docs/microfrontends)\n- [Next.js Multi-Zones](https://nextjs.org/docs/app/building-your-application/deploying/multi-zones)\n\n## Bun Support & Lockfile Detection\n\nTurborepo 2.6+ has **stable Bun support** with granular lockfile analysis:\n\n- **Lockfile format**: Turborepo requires `bun.lock` (text format). If only `bun.lockb` (binary) is found, it errors with a prompt to generate a text lockfile. Generate with `bun install --save-text-lockfile`.\n- **Granular cache invalidation**: Turborepo parses `bun.lock` to detect which specific packages changed and only invalidates caches for affected tasks — not the entire monorepo.\n- **Pruning**: `turbo prune` works with Bun workspaces, generating a minimal lockfile for single-app deploys.\n- **Skip-builds detection**: On Vercel, monorepo workspace detection automatically skips unaffected projects when `bun.lock` changes don't touch a project's dependencies. Combined with `--affected`, only changed packages and their dependents rebuild.\n\n```bash\n# Ensure text lockfile for Turborepo compatibility\nbun install --save-text-lockfile\n\n# Run only affected packages (works with Bun lockfile detection)\nturbo build --affected\n```\n\n> **Known issue**: `turbo prune` with Bun 1.3+ may produce lockfiles with formatting differences that break `bun i --frozen-lockfile`. Track fixes in [turborepo#11007](https://github.com/vercel/turborepo/issues/11007).\n\n## Deploying to Vercel\n\nVercel auto-detects Turborepo and optimizes builds. Each app in `apps/` can be a separate Vercel project with automatic dependency detection.\n\n## When to Use Turborepo\n\n| Scenario | Use Turborepo? |\n|----------|----------------|\n| Single Next.js app | No — Turbopack handles bundling |\n| Multiple apps sharing code | Yes — orchestrate builds |\n| Shared component library | Yes — manage dependencies |\n| CI taking too long | Yes — caching + affected |\n| Team sharing build artifacts | Yes — remote caching |\n| Enforcing architecture boundaries | Yes — boundary rules |\n| Complex multi-step CI pipelines | Yes — task graph + matrix |\n\n## Official Documentation\n\n- [Turborepo Documentation](https://turborepo.dev/repo/docs)\n- [Getting Started](https://turborepo.dev/repo/docs/getting-started)\n- [Crafting Your Repository](https://turborepo.dev/repo/docs/crafting-your-repository)\n- [Task Configuration](https://turborepo.dev/repo/docs/reference/configuration)\n- [Filtering](https://turborepo.dev/repo/docs/crafting-your-repository/running-tasks#using-filters)\n- [GitHub: Turborepo](https://github.com/vercel/turborepo)\n"
}