Turborepo no Node.js

O Turborepo no Node.js organiza tarefas em monorepos e reduz trabalho repetido com cache local ou remoto. Ele lê scripts dos pacotes, constrói um grafo de dependências e executa build, lint, testes e typecheck na ordem correta, paralelizando o que não possui dependência.

Turborepo não substitui npm Workspaces, pnpm ou Yarn. O gerenciador define pacotes e instala dependências; Turbo coordena tarefas. Para obter resultados corretos, cada tarefa precisa declarar dependências, arquivos de entrada, outputs, variáveis de ambiente e comportamento persistente.

Neste guia, você aprenderá a instalar Turborepo, criar turbo.json, definir pipelines, cachear outputs, filtrar pacotes, usar remote cache, configurar CI e evitar caches incorretos.

Estrutura do monorepo

repo/
├── apps/
│   ├── api/
│   └── worker/
├── packages/
│   ├── domain/
│   ├── config/
│   └── observability/
├── package.json
├── package-lock.json
└── turbo.json

O package raiz usa workspaces:

{
  "private": true,
  "workspaces": ["apps/*", "packages/*"]
}

Veja npm Workspaces no Node.js.

Instalação

npm install --save-dev turbo

Adicione scripts apenas na raiz:

{
  "scripts": {
    "build": "turbo run build",
    "test": "turbo run test",
    "lint": "turbo run lint",
    "typecheck": "turbo run typecheck",
    "dev": "turbo run dev"
  }
}

A documentação oficial de execução de tarefas no Turborepo recomenda usar turbo run em scripts e CI para evitar colisões com subcomandos futuros.

Primeiro turbo.json

{
  "$schema": "https://turborepo.com/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": []
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "outputs": []
    }
  }
}

O que significa ^build?

^build significa que o build das dependências do pacote deve terminar antes do build atual. Se api depende de domain, Turbo compila domain primeiro.

Sem o acento:

"dependsOn": ["build"]

a tarefa depende de outra tarefa no mesmo pacote.

Scripts por pacote

Em packages/domain/package.json:

{
  "name": "@empresa/domain",
  "scripts": {
    "build": "tsc -p tsconfig.build.json",
    "test": "node --test",
    "lint": "eslint .",
    "typecheck": "tsc --noEmit"
  }
}

Turbo executa somente scripts que existem no pacote.

Outputs corretos

Cache só restaura arquivos declarados:

"outputs": [
  "dist/**",
  "!dist/cache/**"
]

Se a tarefa gera build, .next ou declarations, inclua os caminhos. Se declarar outputs ausentes, o cache pode informar hit sem restaurar tudo que a próxima tarefa precisa.

Tarefas sem arquivos

"lint": {
  "outputs": []
}

Lint pode ser cacheado pelo código de saída e logs mesmo sem produzir artefato persistente.

Inputs

"test": {
  "inputs": [
    "$TURBO_DEFAULT$",
    "test/**",
    "fixtures/**"
  ],
  "outputs": ["coverage/**"]
}

$TURBO_DEFAULT$ mantém arquivos considerados normalmente e adiciona os extras.

Global dependencies

Arquivos da raiz podem invalidar todas as tarefas:

{
  "globalDependencies": [
    "tsconfig.base.json",
    "eslint.config.js"
  ]
}

Use com moderação; qualquer mudança invalida cache de todo o repositório.

Variáveis de ambiente

"build": {
  "env": ["NODE_ENV", "FEATURE_FLAGS"],
  "outputs": ["dist/**"]
}

Se uma variável altera o output e não está declarada, o cache pode reutilizar artefato incorreto. Não inclua segredos em logs.

Global env

{
  "globalEnv": ["CI"]
}

Variáveis globais invalidam todas as tarefas. Prefira declaração específica por tarefa.

Cache local

Na primeira execução:

npm run build

Na segunda, Turbo restaura resultados quando inputs, dependências, comandos, ambiente e configuração produzem a mesma chave.

Remote Cache

Remote cache compartilha artefatos entre desenvolvedores e CI. Isso reduz builds repetidos, mas exige confiança no backend e proteção dos dados.

npx turbo login
npx turbo link

Em empresas, use credenciais de equipe e política de acesso. Artefatos podem conter sourcemaps, código e resultados de testes.

Assinatura de artefatos

Quando disponível, configure verificação de assinatura ou integridade para reduzir risco de cache adulterado. Não trate remote cache como origem confiável sem controles.

Filtros por pacote

npx turbo run build --filter=@empresa/api

Incluindo dependências:

npx turbo run build --filter=@empresa/api...

Incluindo dependentes:

npx turbo run test --filter=...@empresa/domain

Filtro por diretório

npx turbo run lint --filter="./packages/*"

Filtro por alterações Git

npx turbo run build --filter=[main...HEAD]

Esse filtro seleciona pacotes afetados, mas dependências e dependentes ainda precisam ser considerados conforme a tarefa.

Dry run

npx turbo run build --dry=json

Use para entender o grafo, tasks, inputs, outputs e motivos de cache miss.

Execução paralela

Turbo inicia tarefas assim que suas dependências terminam. Não force paralelismo em migrations ou comandos que usam o mesmo recurso compartilhado.

Tarefas persistentes

"dev": {
  "cache": false,
  "persistent": true
}

Servidores de desenvolvimento não terminam e não devem ser cacheados. Dependências de uma tarefa persistente precisam ser configuradas com cuidado.

Interatividade

Comandos que exigem entrada humana não funcionam bem no grafo ou CI. Crie flags não interativas e defaults seguros.

CI com GitHub Actions

- uses: actions/checkout@v6
  with:
    fetch-depth: 0

- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: npm

- run: npm ci
- run: npx turbo run lint typecheck test build

Para filtros por Git, o histórico precisa estar disponível. Veja CI para Node.js com GitHub Actions.

Remote cache no CI

Injete token como secret e restrinja o escopo:

env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: minha-equipe

Não exponha o token em pull requests de forks.

Prune para Docker

npx turbo prune @empresa/api --docker

O comando gera um subconjunto do monorepo com manifests e fontes necessárias ao pacote alvo. Isso melhora cache do Docker e reduz contexto.

Depois:

COPY out/json/ .
RUN npm ci
COPY out/full/ .
RUN npx turbo run build --filter=@empresa/api

Consulte Docker Multi-stage para Node.js.

Cache do gerenciador versus Turbo

O cache de npm guarda downloads; o cache de Turbo guarda resultados de tarefas. Use ambos. Não cacheie node_modules indiscriminadamente.

TypeScript

Pacotes compartilhados devem ter references ou build explícito. Turbo ordena tarefas, mas não corrige imports internos ou declarations.

Veja TypeScript ESM no Node.js.

Lint e Prettier

Lint pode rodar por pacote; formatação geralmente roda na raiz:

{
  "scripts": {
    "format:check": "prettier . --check"
  }
}

Consulte ESLint Flat Config no Node.js e Prettier no Node.js.

Cache incorreto

Sinais:

• build antigo após mudar variável;
• declarations ausentes;
• testes passando apenas com cache;
• arquivos gerados fora de outputs;
• dependência externa não declarada.

Execute:

npx turbo run build --force

Se o resultado muda, revise inputs, env e outputs.

Não cacheie efeitos externos

Migrations, deploy, publicação e envio de mensagens não devem ser tratados como tarefas cacheáveis. Um cache hit não pode substituir um efeito que precisa ocorrer.

"deploy": {
  "cache": false,
  "dependsOn": ["build"]
}

Logs

Use outputLogs para reduzir ruído, mas preserve logs de falha. Em CI, armazene artifacts quando necessário.

Telemetria

Verifique política de telemetria da versão usada e configure conforme os requisitos da organização. Não dependa de defaults sem revisão.

Comparação com npm Workspaces

Workspaces instalam e vinculam pacotes. Turborepo coordena tarefas e cache. Um projeto pequeno pode usar apenas workspaces; Turbo ganha valor quando tarefas repetidas e grafo começam a dominar o tempo.

Comparação com Nx

Nx oferece recursos amplos de geração, plugins e análise de projetos. Turborepo tende a ser menor e alinhado a scripts existentes. O próximo artigo apresenta Nx.

Erros comuns

• Turbo dentro de cada pacote: recursão.
• Outputs incompletos: cache restaura artefato parcial.
• Env ausente: resultado errado é reutilizado.
• Cachear deploy: efeito externo é pulado.
• Persistente com cache: comportamento incorreto.
• Filtro sem dependentes: quebra não é detectada.
• Remote cache exposto: artefatos vazam.
• Sem histórico Git: filtro por mudanças falha.

Configuração recomendada

{
  "$schema": "https://turborepo.com/schema.json",
  "globalDependencies": ["tsconfig.base.json"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"],
      "env": ["NODE_ENV"]
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "lint": {
      "outputs": []
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Conclusão

O Turborepo no Node.js acelera monorepos ao construir um grafo de tarefas e reutilizar resultados. A ferramenta oferece maior benefício quando scripts já são determinísticos e outputs estão claramente definidos.

Declare dependências, env e artefatos, não cacheie efeitos externos e proteja remote cache. Com workspaces e CI bem configurados, Turborepo reduz tempo sem sacrificar correção.