Claude Code e Turborepo: guia prático para monorepos

Por que juntar Claude Code e Turborepo

Um monorepo coloca várias aplicações e pacotes compartilhados em um único repositório. No início, apps/web e packages/ui parecem suficientes. Depois chegam painel administrativo, documentação, utilitários, mais pipelines e uma CI que executa tudo mesmo quando a mudança é pequena.

Turborepo organiza isso com um grafo de tarefas e cache. Claude Code ajuda quando é usado como revisor do repositório: ele lê package.json, explica dependências entre pacotes, encontra outputs ausentes e sugere comandos de CI limitados ao que realmente mudou.

Este guia considera Turborepo v2 em 2 de junho de 2026. Em turbo.json, a chave correta é tasks, não o antigo pipeline. Antes de adaptar os exemplos, consulte as fontes oficiais: Turborepo configuration, turbo run, Remote Caching e Claude Code memory.

Para continuar no ClaudeCodeLab, veja também gestão de monorepos, pnpm workspace com Claude Code e CI/CD com Claude Code.

Estrutura alvo e três casos de uso

A estrutura alvo é um monorepo TypeScript pequeno sobre pnpm workspace. Começar pequeno é uma decisão prática: Claude Code segue melhor limites explícitos do que pacotes vagos chamados shared ou common.

flowchart LR
  web["apps/web\nApp do cliente"] --> ui["packages/ui\nUI compartilhada"]
  admin["apps/admin\nApp administrativa"] --> ui
  web --> utils["packages/utils\nFunções compartilhadas"]
  admin --> utils
  ui --> tsconfig["packages/tsconfig\nConfig TS"]
  utils --> tsconfig

O primeiro caso é um produto com app do cliente e app administrativa compartilhando botões, formulários e validadores. Separar packages/ui de packages/utils evita que Claude Code misture componentes visuais com lógica de negócio.

O segundo caso é uma plataforma de conteúdo ou documentação. Landing page, docs e painel interno podem viver juntos, mas rodar tudo a cada PR fica caro. --affected e --filter verificam apenas os pacotes alterados e os dependentes.

O terceiro caso é um SaaS com fluxo de receita. Pricing, signup, configurações de conta e admin costumam compartilhar pacotes pequenos. Se lint, type-check, test e build são estáveis, Claude Code pode mudar um CTA sem escapar da proteção da CI.

Copie a estrutura mínima

Primeiro defina o formato do repositório. O ponto não é criar muitos pacotes, e sim dar a cada um uma responsabilidade clara.

acme-monorepo/
  apps/
    web/
      package.json
      src/
    admin/
      package.json
      src/
  packages/
    ui/
      package.json
      src/
    utils/
      package.json
      src/
    tsconfig/
      package.json
      base.json
  pnpm-workspace.yaml
  package.json
  turbo.json
  CLAUDE.md

O pnpm-workspace.yaml pode ficar simples.

packages:
  - "apps/*"
  - "packages/*"

No package.json da raiz, deixe comandos Turborepo que a equipe e Claude Code possam reutilizar. Em 2 de junho de 2026, verifiquei turbo@2.9.16 e pnpm@11.5.1; em projeto real, o lockfile garante a reprodução.

{
  "name": "acme-monorepo",
  "private": true,
  "packageManager": "pnpm@11.5.1",
  "scripts": {
    "dev": "turbo dev",
    "build": "turbo run build",
    "lint": "turbo run lint",
    "test": "turbo run test",
    "type-check": "turbo run type-check",
    "check": "turbo run lint type-check test build",
    "check:affected": "turbo run lint type-check test build --affected"
  },
  "devDependencies": {
    "turbo": "^2.9.16",
    "typescript": "^5.8.3"
  }
}

Pacotes internos devem usar workspace:*. Assim o package manager resolve o pacote dentro do workspace em vez de baixar um pacote de mesmo nome por acidente.

{
  "name": "@acme/ui",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "lint": "eslint src --max-warnings=0",
    "type-check": "tsc -p tsconfig.json --noEmit",
    "test": "vitest run"
  },
  "devDependencies": {
    "@acme/tsconfig": "workspace:*",
    "typescript": "^5.8.3",
    "vitest": "^3.1.0",
    "eslint": "^9.25.0"
  }
}

Defina turbo.json com tasks e outputs

O turbo.json da raiz é o contrato de tarefas do repositório. Cada chave em tasks procura scripts de mesmo nome nos pacotes. ^build significa que os pacotes dependência devem executar build antes do pacote atual.

{
  "$schema": "https://turborepo.dev/schema.json",
  "globalDependencies": ["pnpm-lock.yaml", "tsconfig.base.json", ".env.example"],
  "globalEnv": ["NODE_ENV"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**", "out/**"]
    },
    "lint": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "type-check": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

outputs informa quais artefatos podem ser restaurados do cache. Se for estreito demais, a cache pouco ajuda. Se for amplo demais, temporários e caches internas do framework entram nos artefatos. Em Next.js, excluir .next/cache/** costuma ser um bom padrão.

Quando uma aplicação tem artefatos diferentes, adicione um turbo.json dentro do pacote. Arrays substituem valores herdados por padrão; use $TURBO_EXTENDS$ no começo para acrescentar.

{
  "extends": ["//"],
  "tasks": {
    "build": {
      "outputs": ["$TURBO_EXTENDS$", ".next/**", "!.next/cache/**"],
      "env": ["NEXT_PUBLIC_API_URL"]
    }
  }
}

Deixe a CI previsível

Turborepo mostra valor na CI, mas --affected precisa de histórico Git. Em GitHub Actions, um checkout raso pode fazer todos os pacotes parecerem alterados. Use fetch-depth: 0.

name: turbo-ci

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  verify:
    runs-on: ubuntu-latest
    env:
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
      TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v4
        with:
          version: 11.5.1
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm turbo run lint type-check test build --affected
      - run: pnpm turbo run build --dry=json > turbo-plan.json
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: turbo-plan
          path: turbo-plan.json

Para Remote Cache, conecte o repositório localmente com pnpm dlx turbo login e pnpm dlx turbo link, e passe TURBO_TOKEN e TURBO_TEAM como secrets na CI. Logs também podem ser artefatos, então scripts de build não devem imprimir API keys, dados de clientes ou session tokens.

Registre comandos comuns em CLAUDE.md.

pnpm turbo run build --dry=json
pnpm turbo run build --filter=@acme/web...
pnpm turbo run test --filter=...[origin/main]
pnpm turbo run lint --filter=!./apps/docs
pnpm turbo run build --cache=local:rw,remote:r
pnpm turbo run build --force

Prompt para Claude Code

Não peça apenas “configure Turborepo”. Dê limites, proibições e comandos de verificação.

Este repositório é um monorepo Turborepo v2 + pnpm workspace.

Limites:
- apps/* são aplicações implantáveis.
- packages/ui contém apenas componentes visuais.
- packages/utils contém apenas funções independentes de framework.
- packages/* não deve depender de apps/*.
- turbo.json deve usar tasks, não pipeline.

Tarefa:
1. Leia package.json e turbo.json, depois explique o grafo de dependência das tasks.
2. Aponte outputs ausentes ou suspeitos para cache.
3. Se mudanças forem necessárias, faça o menor diff seguro.
4. Execute estes comandos e reporte o resultado:

pnpm turbo run lint type-check test build --affected
pnpm turbo run build --dry=json

Esse prompt reduz o erro comum da IA: uma reescrita grande e lateral. Também ajuda a bloquear propostas ruins, como chamadas HTTP em packages/ui, import de Next.js em packages/utils ou CI baseada apenas em build completo.

Erros comuns

O primeiro erro é copiar exemplos antigos com pipeline. Turborepo v2 usa tasks. Em migrações, peça a Claude Code para explicar cada chave contra a documentação oficial.

O segundo erro é cachear demais. Não coloque node_modules/**, logs temporários ou caches internas não implantáveis em outputs. Cacheie artefatos de build, não o workspace inteiro.

O terceiro erro é usar --affected sem histórico Git suficiente. Sem base e head no checkout, Turborepo não calcula corretamente o conjunto de pacotes.

O quarto erro é pedir trabalho demais de uma vez. Introduza Turborepo, depois scripts da raiz, depois CI. Separação de pacotes, migração de ESLint e upgrades de dependência devem ser passos próprios.

O quinto erro é compartilhar demais. Um packages/shared enorme transforma mudanças pequenas em mudanças globais. ui, utils, contracts e tsconfig tornam o grafo mais legível.

Monetização e próximos passos

Turborepo não é apenas ferramenta de velocidade. Ele protege caminhos de receita. Um site de conteúdo bloqueia publicação quando o build quebra. Um SaaS valida pricing, signup, configurações e admin em um fluxo repetível. Em times de consultoria, CI menor reduz espera de review.

ClaudeCodeLab pode ajudar equipes a transformar isso em prática: CLAUDE.md, limites de package, comandos de CI, prompts de review e regras de rollout. Para estudo próprio, siga com gestão de monorepos e CI/CD com Claude Code. Para adoção em equipe, comece em training / consultation.

Resultado ao testar

Masa aplicou esse padrão em um repositório pequeno com duas apps Vite e um pacote UI compartilhado. A primeira execução rodou todas as tasks; as seguintes mostraram cache hit em build e type-check. O primeiro outputs estava amplo demais e salvava caches internas do framework, deixando os artefatos de CI ruidosos. A versão estável foi a deste artigo: tasks v2, outputs estreitos, verificação affected e prompt Claude Code que revisa limites antes de editar arquivos.