Turborepo: Otimizando Monorepos com Build Cache Inteligente e Paralelismo de Tarefas

O que é o Turborepo?

O Turborepo é uma ferramenta de build system inteligente para monorepos, desenvolvida pela Vercel e adotada por empresas como Netflix, Stripe, Shopify e Disney. Diferente de soluções tradicionais, o Turborepo não gerencia pacotes — ele orquestra tarefas entre pacotes, otimizando o fluxo de build com cache remoto, paralelismo e execução seletiva baseada em dependências.

Monorepos (monolithic repositories) são repositórios únicos que armazenam múltiplos projetos ou pacotes. Embora poderosos, eles sofrem com builds lentos, dependências complexas e execução sequencial de tarefas. O Turborepo resolve exatamente esses problemas.

Por que usar Turborepo em vez de outras soluções?

Existem várias ferramentas no ecossistema de monorepos — Nx, Lerna, Bazel, Rush, pnpm workspaces. O Turborepo se destaca por três pilares:

Cache inteligente: tarefas que já foram executadas com as mesmas entradas nunca precisam rodar novamente. O cache funciona localmente e remotamente (via Vercel Remote Caching ou serviços compatíveis com S3).
Paralelismo máximo: o Turborepo analisa o grafo de dependências entre pacotes e executa tarefas independentes em paralelo, respeitando a ordem correta onde há dependências.
Zero configuração inicial: com apenas um arquivo turbo.json minimalista, você já obtém ganhos significativos de performance sem precisar reestruturar seu repositório.

Arquitetura e funcionamento interno

O Turborepo opera como um orchestrator de tarefas. Ele não substitui seu package manager (npm, yarn, pnpm) nem seu bundler (webpack, Vite, esbuild). Em vez disso, ele adiciona uma camada de inteligência sobre eles.

O fluxo básico de execução é:

O usuário define tarefas no turbo.json — por exemplo, build, test, lint.
Cada tarefa especifica seus inputs (quais arquivos determinam cache hit) e seus outputs (quais artefados são gerados).
O Turborepo mapeia o grafo de dependências entre pacotes e determina a ordem de execução ótima.
Tarefas independentes rodam em paralelo. Tarefas com resultados cacheados são puladas instantaneamente.
Ao final, logs são agregados com um visualizador interativo (turbo run build --profile).

Configuração prática de um monorepo com Turborepo

Vamos criar um monorepo básico com dois pacotes: uma aplicação Next.js e uma biblioteca compartilhada de UI.

# Inicializar o monorepo
mkdir meu-monorepo && cd meu-monorepo
npm init -y
npm install -D turbo
npx turbo init

# Criar estrutura de pacotes
mkdir -p apps/web packages/ui

# app/web/package.json
cat > apps/web/package.json << 'EOF'
{
  "name": "web",
  "dependencies": { "ui": "workspace:*" },
  "scripts": { "build": "next build", "dev": "next dev" }
}
EOF

# packages/ui/package.json
cat > packages/ui/package.json << 'EOF'
{
  "name": "ui",
  "scripts": { "build": "tsc", "lint": "eslint ." }
}
EOF

O arquivo central de configuração é o turbo.json:

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    },
    "lint": {},
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Neste exemplo, o ^build indica que antes de buildar o pacote web, o Turborepo deve buildar suas dependências (ui primeiro). A tarefa lint pode rodar em paralelo com qualquer outra.

Cache remoto: builds instantâneos em CI/CD

O recurso mais poderoso do Turborepo é o Remote Caching. Times inteiros compartilham o mesmo cache — o que um desenvolvedor buildou localmente, o CI não precisa rebuildar.

# Habilitar cache remoto via Vercel
npx turbo login
npx turbo link

# Ou usar cache remoto self-hosted com S3
# Configure as variáveis de ambiente:
# TURBO_API, TURBO_TOKEN, TURBO_TEAM

O cache é granular por tarefa e por hash do conteúdo de entrada. Se apenas um pacote foi modificado, apenas ele será rebuildado — os demais retornam do cache em milissegundos.

Escalando com filtros e escopos

Em repositórios grandes, você não precisa executar todas as tarefas de todos os pacotes o tempo todo. O Turborepo oferece filtros precisos:

# Executar build apenas nos pacotes modificados desde a branch main
turbo run build --filter=...[origin/main]

# Executar teste apenas em pacotes que dependem de 'ui'
turbo run test --filter=...ui

# Ignorar completamente certos diretórios
turbo run build --filter=!./apps/legacy

Esses filtros permitem que PRs pequenos executem CI em segundos, não minutos.

Turborepo vs Nx: quando usar cada um

Ambas as ferramentas resolvem problemas similares, mas com filosofias diferentes:

Característica	Turborepo	Nx
Foco principal	Build system e cache	Framework completo de monorepo
Gerenciamento de pacotes	Delega ao npm/yarn/pnpm	Próprio gerenciador
Curva de aprendizado	Baixa	Média-Alta
Geração de código	Não nativo	`nx generate`
Cache remoto	Vercel ou auto-hospedado	Nx Cloud ou auto-hospedado
Suporte a linguagens	JS/TS (+ Go, Rust com adaptações)	JS/TS, Java, Python, Go, Rust, C#

Escolha Turborepo se você quer simplicidade máxima e já usa o ecossistema JavaScript/TypeScript. Escolha Nx se precisa de geração de código, suporte a múltiplas linguagens, ou um ecossistema mais opinado.

Integração com pipelines CI/CD

O Turborepo se integra naturalmente com GitHub Actions, GitLab CI, CircleCI e qualquer plataforma de CI. Um workflow típico no GitHub Actions:

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npx turbo run build lint test
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}

A flag fetch-depth: 2 permite que o Turborepo detecte quais arquivos mudaram entre commits, otimizando ainda mais o cache.

Casos de uso reais

Vercel: usa Turborepo internamente para gerenciar todos os seus projetos front-end e bibliotecas compartilhadas.
Netflix: utiliza Turborepo no Studio UI Platform para coordenar builds entre times.
Stripe: gerencia bibliotecas de design system e SDKs internos com Turborepo.
Disney+: a plataforma de streaming usa Turborepo para coordenar aplicações web modulares.

Prós, contras e boas práticas

Vantagens

Redução drástica do tempo de build (50-90% com cache remoto)
Curva de aprendizado baixíssima — comece em minutos
Cache distribuído entre times sem configuração complexa
Logs interativos com flamegraph para debug de performance
Open-source e ativamente mantido pela Vercel

Desvantagens

Foco principal em JS/TS — suporte a outras linguagens é limitado
Não oferece scaffolding de código como Nx
Cache remoto da Vercel requer conta (gratuita para projetos pessoais)
Para monorepos muito grandes (+100 pacotes), o Nx pode ser mais adequado

Boas práticas

Sempre especifique inputs nas tarefas para maximizar cache hits
Use outputs explícitos — nunca marque como vazio se a tarefa gera artefatos
Configure cache: false para tarefas não determinísticas (dev servers, watchers)
Mantenha as versões do Turborepo sincronizadas entre times via package.json
Utilize turbo.json no nível da raiz com extends para configs herdadas

Conclusão

O Turborepo representa um avanço significativo na gestão de monorepos modernos. Sua abordagem minimalista — focada exclusivamente em build caching e paralelismo — entrega ganhos imediatos com configuração quase zero. Para times que trabalham com JavaScript e TypeScript, é uma ferramenta indispensável no stack de desenvolvimento.

Se você ainda sofre com builds lentos no CI, desenvolvedores rebuildando o que já foi buildado, ou scripts de build frágeis que rodam em série, experimente migrar para Turborepo. Em questão de horas, não dias, você verá resultados mensuráveis.

Comece hoje com npx create-turbo@latest e transforme a produtividade do seu time.

Programação

Entrar em contato

Entre em contato