Turborepo para Node

O Turborepo orquestra tarefas de workspace com cache remoto para que pacotes inalterados pulem reconstruções em CI e localmente.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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

npx turbo run build test typecheck

Quando usar isso:

• Monorepo com 3+ pacotes e repetição de build/test em CI.
• Bibliotecas compartilhadas devem compilar antes que os aplicativos façam a verificação de tipos.
• Você deseja acertos de cache entre desenvolvedores e executores de CI.

Exemplo de Trabalho

platform/
  turbo.json
  package.json          # workspaces
  apps/
    api/package.json
  packages/
    shared/package.json

// package.json (root)
{
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "build": "turbo run build",
    "test": "turbo run test",
    "dev": "turbo run dev --parallel"
  },
  "devDependencies": {
    "turbo": "^2.3.0",
    "typescript": "^5.6.0"
  }
}

// packages/shared/package.json
{
  "name": "@acme/shared",
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "test": "node --import tsx --test"
  }
}

// apps/api/package.json
{
  "name": "@acme/api",
  "dependencies": { "@acme/shared": "workspace:*", "fastify": "^5.0.0" },
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "dev": "tsx watch src/server.ts",
    "test": "node --import tsx --test"
  }
}

npm install
npx turbo run build --filter=@acme/api...

O que isso demonstra:

• ^build executa as compilações dos pacotes dependentes antes dos dependentes.
• --filter=@acme/api... inclui a API e suas dependências de workspace.
• outputs informa ao Turbo o que armazenar em cache entre as execuções.

Mergulho Profundo

Como Funciona

• O Turbo gera hashes para as entradas das tarefas (código-fonte, variáveis de ambiente, dependências) e restaura os outputs do cache em caso de acerto de cache.
• dependsOn constrói um DAG (Grafo Acíclico Dirigido); test espera pelos artefatos de build.
• O cache remoto (Vercel ou auto-hospedado) compartilha acertos entre máquinas de CI.
• Tarefas dev geralmente são persistent: true e não são cacheadas.

Configuração de Tarefas

Notas de TypeScript

{
  "tasks": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
    "typecheck": { "dependsOn": ["^build"] }
  }
}

• Separe typecheck de build se quiser trabalhos de CI mais rápidos que pulem a emissão quando apenas verificarem tipos.
• Certifique-se de que cada tsconfig de pacote emita para dist/ consistentemente para os caminhos de cache.

Armadilhas

• outputs ausentes - O Turbo não armazena nada útil em cache; cada build é executado novamente por completo. Correção: declare dist/** para cada tarefa de compilação.
• Sintaxe de filtro incorreta - Apenas @acme/api pula as compilações de dependência. Correção: use @acme/api... (três pontos) para a cadeia de dependentes.
• Cache de testes com efeitos colaterais - Testes que acessam o banco de dados real obtêm falsos positivos do cache. Correção: exclua testes de integração de tarefas cacheadas ou use inputs únicos.
• Segredos de ambiente no hash - Listas env invalidam o cache quando os tokens mudam. Correção: liste apenas variáveis de ambiente que afetam a saída da compilação.
• Tarefa dev cacheada por engano - O modo de observação não deve ser cacheado. Correção: "persistent": true e sem outputs em dev.

Alternativas

FAQs

npx turbo run dev --filter=@acme/api

Relacionados

• Workspaces & Monorepos - links de workspace
• Monorepo Multi-Serviço - limites implantáveis
• Nx para Backends Node - orquestração alternativa

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.