Monorepos com Nx e Turborepo: Como Gerenciar Múltiplos Projetos Sem Perder a Sanidade

Olá HaWkers, sua empresa tem frontend, backend, mobile app, bibliotecas compartilhadas, tudo em repositórios separados gerando caos de versionamento?

Monorepos surgiram como solução para esse problema. Google, Facebook, Microsoft - gigantes tech mantêm MILHÕES de linhas de código em repositórios únicos. Em 2025, ferramentas como Nx e Turborepo tornaram essa abordagem acessível para qualquer time. Vamos explorar.

O que é Monorepo e Por que Importa

Monorepo: Repositório Git único contendo múltiplos projetos relacionados (apps, libs, packages).

Não confunda com:

Monolito: Arquitetura de aplicação única
Multirepo: Cada projeto em repositório separado

Nx: O Gigante Completo

Nx é desenvolvido pela Nrwl e é o mais poderoso e complexo. Google usa Nx internamente para gerenciar Angular, e a ferramenta suporta QUALQUER stack.

Setup Inicial

# Criar workspace Nx
npx create-nx-workspace@latest my-monorepo

# Escolha: integrated (recomendado) ou package-based

# Estrutura gerada:
my-monorepo/
├── apps/
│   ├── frontend/          # App React/Vue/Angular
│   ├── backend/           # API Node.js
│   └── mobile/            # React Native
├── libs/
│   ├── ui/                # Componentes compartilhados
│   ├── data-access/       # Camada de dados
│   └── utils/             # Utilitários
├── nx.json                # Configuração Nx
└── package.json

Criando Apps e Libs

# Gerar aplicação React
nx g @nx/react:app frontend

# Gerar biblioteca compartilhada
nx g @nx/react:lib ui --directory=libs/ui

# Gerar API Node.js
nx g @nx/node:app backend

# Gerar lib TypeScript pura
nx g @nx/js:lib utils --directory=libs/utils

Dependency Graph: Visualização Poderosa

# Ver grafo de dependências
nx graph

# Nx gera visualização interativa mostrando:
# - Quais apps dependem de quais libs
# - Dependências circulares (erros!)
# - Impacto de mudanças

nx dependency graph

Builds Inteligentes: Affected Commands

# Testar APENAS o que mudou
nx affected:test

# Build apenas apps/libs afetados
nx affected:build

# Lint apenas código modificado
nx affected:lint

# Como Nx sabe o que mudou?
# Compara com branch base (ex: main) e analisa dependências

Exemplo Prático

# Você altera libs/utils/src/date.ts

# Nx detecta automaticamente:
# - apps/frontend depende de libs/utils
# - apps/backend depende de libs/utils
# - apps/mobile NÃO depende de libs/utils

# Comando affected:build só rebuilda:
nx affected:build
# ✓ libs/utils
# ✓ apps/frontend
# ✓ apps/backend
# ⊗ apps/mobile (pulado!)

# Economia: 40-60% de tempo de build

Turborepo: Simplicidade e Velocidade

Turborepo (criado por Vercel) foca em simplicidade e caching agressivo. Menos features que Nx, mas setup instantâneo.

Setup Turborepo

# Criar monorepo
npx create-turbo@latest my-turborepo

# Estrutura gerada:
my-turborepo/
├── apps/
│   ├── web/               # Next.js app
│   └── docs/              # Documentação
├── packages/
│   ├── ui/                # Component library
│   ├── config/            # Shared configs
│   └── tsconfig/          # TypeScript configs
├── turbo.json             # Pipeline config
└── package.json

Configuração de Pipeline

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

Executando Tasks

# Build tudo (com cache)
turbo run build

# Test em paralelo máximo
turbo run test

# Dev mode em múltiplos apps
turbo run dev --parallel

# Cache remoto (Vercel)
turbo run build --token=<your-token>
# Cache compartilhado entre todo o time!

Nx vs Turborepo: Comparação Direta

Performance: Nx Vence em Escala

Benchmarks oficiais (large-monorepo):

Nx: ~50s para build completo
Turborepo: ~350s para build completo
Nx é 7x mais rápido em monorepos grandes!

Simplicidade: Turborepo Vence

# Turborepo: Setup em minutos
npx create-turbo@latest

# Nx: Mais decisões iniciais
npx create-nx-workspace@latest
# → Escolher preset
# → Configurar CI
# → Definir estratégia de caching

Ecossistema: Nx Mais Completo

Nx oferece:

Plugins oficiais (React, Angular, Node, Next, Nest, etc)
Generators (code scaffolding automático)
Migrate (atualização automática de dependências)
Nx Cloud (caching distribuído enterprise)

Turborepo oferece:

Core build/cache system (extremamente rápido)
Integração perfeita com Vercel
Simplicidade (menos abstrações)

Quando Usar Cada Um?

Use Nx se:

Monorepo grande (10+ apps/libs)
Time grande (15+ devs)
Múltiplas tecnologias (React + Angular + Node)
Precisa de CI/CD complexo
Quer ferramentas avançadas (generators, migrations)

Use Turborepo se:

Monorepo pequeno/médio (< 10 projetos)
Stack homogêneo (ex: apenas Next.js)
Time pequeno (< 10 devs)
Valoriza simplicidade sobre features
Usa Vercel para deploy

Exemplo Prático: Shared Components Library

// packages/ui/src/Button.tsx
import React from 'react';

export interface ButtonProps {
  variant?: 'primary' | 'secondary';
  children: React.ReactNode;
  onClick?: () => void;
}

export function Button({ variant = 'primary', children, onClick }: ButtonProps) {
  return (
    <button
      className={`btn btn-${variant}`}
      onClick={onClick}
    >
      {children}
    </button>
  );
}

// apps/web/pages/index.tsx
import { Button } from '@my-monorepo/ui';

export default function Home() {
  return (
    <div>
      <h1>Meu App</h1>
      <Button variant="primary">Click Me</Button>
    </div>
  );
}

// apps/admin/pages/dashboard.tsx
import { Button } from '@my-monorepo/ui';

export default function Dashboard() {
  return (
    <div>
      <h1>Admin Dashboard</h1>
      <Button variant="secondary">Settings</Button>
    </div>
  );
}

// Mudanças em packages/ui afetam AMBOS os apps
// Nx/Turborepo rebuildam automaticamente

CI/CD Otimizado para Monorepos

# .github/workflows/ci.yml (Nx)
name: CI

on: [push]

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0 # Importante para affected

      - uses: actions/setup-node@v3

      - run: npm ci

      # Roda APENAS testes afetados
      - run: npx nx affected:test --base=origin/main

      # Build apenas apps modificados
      - run: npx nx affected:build --base=origin/main

      # Deploy condicional
      - run: npx nx affected --target=deploy --base=origin/main

# .github/workflows/ci.yml (Turborepo)
name: CI

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-node@v3

      - run: npm ci

      # Cache remoto Vercel
      - run: npx turbo run test --token=${{ secrets.TURBO_TOKEN }}

      - run: npx turbo run build --token=${{ secrets.TURBO_TOKEN }}

Armadilhas Comuns

1. Dependências Fantasmas

App funciona localmente mas quebra em produção porque dependia de lib não declarada.

Solução: Use --strict mode no Nx, ou externals no Turborepo.

2. Builds Lentos Inicialmente

Primeira build pode ser MUITO lenta.

Solução: Configure cache remoto (Nx Cloud ou Turborepo Remote Cache).

3. Conflitos de Versão

Múltiplos apps precisam de versões diferentes de React.

Solução: Use resolutions (Yarn) ou overrides (npm) cuidadosamente.

O Futuro dos Monorepos

Rust-based tools (como Turbopack) trazendo performance 10x superior
AI-powered refactoring que entende dependências complexas
Distributed execution nativo (builds em múltiplas máquinas)

Monorepos não são para todos os projetos, mas para times que gerenciam múltiplos apps relacionados, são game changer. Escolha Nx para poder máximo, Turborepo para simplicidade máxima.

Se você quer entender padrões que ajudam em qualquer projeto, grande ou pequeno, veja: Atalhos para Operações Condicionais onde exploramos código limpo e eficiente.

Bora pra cima! 🦅

💻 Domine JavaScript de Verdade

O conhecimento que você adquiriu neste artigo é só o começo. Há técnicas, padrões e práticas que transformam desenvolvedores iniciantes em profissionais requisitados.

Invista no Seu Futuro

Preparei um material completo para você dominar JavaScript:

Formas de pagamento:

R$9,90 (pagamento único)

📖 Ver Conteúdo Completo