6 min leitura • Guide 361 of 877
Estratégias de Gestão de Monorepo
Monorepos abrigam múltiplos projetos em um único repositório. Feito bem, eles simplificam compartilhamento e consistência. Feito mal, eles se tornam lentos, confusos e difíceis de manter. Este guia cobre abordagens práticas para gestão de monorepo.
Trade-offs de Monorepo
| Benefício | Desafio |
|---|---|
| Compartilhamento de código | Complexidade de build |
| Mudanças atômicas | Tempo de CI |
| Consistência | Gestão de permissões |
| Visibilidade | Tooling necessário |
Estrutura de Repositório
Organizando o Monorepo
ESTRUTURA DE MONOREPO
═════════════════════
ESTRUTURA TÍPICA:
─────────────────────────────────────
monorepo/
├── apps/ # Aplicações
│ ├── web/ # Frontend web
│ ├── api/ # Backend API
│ ├── mobile/ # App mobile
│ └── admin/ # Dashboard admin
├── packages/ # Bibliotecas compartilhadas
│ ├── ui/ # Componentes UI
│ ├── utils/ # Utilitários
│ ├── config/ # Config compartilhada
│ └── types/ # Definições de tipos
├── tools/ # Ferramentas de build
│ └── scripts/
├── package.json # Package root
├── nx.json / turbo.json # Config de ferramenta monorepo
└── README.md
CONVENÇÕES DE NAMING:
─────────────────────────────────────
Packages:
├── @org/web (apps)
├── @org/api (apps)
├── @org/ui (packages)
├── @org/utils (packages)
├── Naming com escopo
└── Ownership claro
OWNERSHIP:
─────────────────────────────────────
Definir owners:
├── apps/web → Time Web
├── apps/api → Time Backend
├── packages/ui → Time Design Systems
├── packages/utils → Time Platform
├── Arquivo CODEOWNERS
└── Responsabilidade clara
Gestão de Dependências
Dependências Internas
GESTÃO DE DEPENDÊNCIAS
══════════════════════
DEPENDÊNCIAS INTERNAS:
─────────────────────────────────────
apps/web/package.json:
{
"dependencies": {
"@org/ui": "workspace:*",
"@org/utils": "workspace:*"
}
}
Usando workspace protocol:
├── Linka para pacote local
├── Sem gestão de versão
├── Sempre usa atual
├── Updates atômicos
└── Deps internas simples
GRAFO DE DEPENDÊNCIAS:
─────────────────────────────────────
┌─────────┐
│ apps │
└────┬────┘
│ depende de
┌────▼────┐
│packages │
└────┬────┘
│ pode depender de
┌────▼────┐
│packages │
└─────────┘
Regras:
├── Apps dependem de packages
├── Packages podem depender de packages
├── Sem dependências circulares
├── Packages não dependem de apps
└── Hierarquia clara
DEPENDÊNCIAS EXTERNAS:
─────────────────────────────────────
Estratégias:
├── Hoist para root (mesma versão)
├── Ou permitir versões por-pacote
├── Consistência preferida
├── Dependabot/Renovate para updates
└── Política clara
Build e CI
Builds Incrementais
OTIMIZAÇÃO DE BUILD
═══════════════════
BUILDS INCREMENTAIS:
─────────────────────────────────────
Conceito:
├── Só build pacotes alterados
├── + seus dependentes
├── Não o monorepo inteiro
├── Massiva economia de tempo
└── Essencial em escala
EXEMPLO COM NX:
─────────────────────────────────────
# Build apenas afetados desde main
nx affected:build --base=main
# Run tests apenas em pacotes alterados
nx affected:test --base=main
# Com caching remoto
nx affected:build --base=main --cache
EXEMPLO COM TURBOREPO:
─────────────────────────────────────
# Build com caching
turbo run build --filter=...[origin/main]
# Execução paralela
turbo run test --parallel
CACHING REMOTO:
─────────────────────────────────────
├── Cache de artifacts de build
├── Compartilhado entre CI e devs
├── Se mesmo input → usa cache
├── Dramaticamente reduz builds
└── Nx Cloud, Turborepo Remote Cache
RESULTADO:
─────────────────────────────────────
Sem otimização:
├── Build de 30 minutos
├── Todo commit rebuild tudo
└── Feedback lento
Com otimização:
├── Build de 2-5 minutos
├── Apenas mudanças
└── Feedback rápido
Workflow de Time
Code Ownership
OWNERSHIP EM MONOREPO:
┌─────────────────────────────────────────────────────────────┐
│ │
│ CODEOWNERS: │
│ ──────────── │
│ │
│ # .github/CODEOWNERS │
│ /apps/web/ @org/web-team │
│ /apps/api/ @org/backend-team │
│ /packages/ui/ @org/design-system-team │
│ /packages/utils/ @org/platform-team │
│ │
│ COMO FUNCIONA: │
│ ────────────── │
│ • PR toca apps/web → web-team aprova │
│ • PR toca múltiplas áreas → múltiplos approvals │
│ • Ownership claro │
│ • Proteção de áreas críticas │
│ │
│ BOUNDARIES: │
│ ─────────── │
│ • Times podem commitar em suas áreas livremente │
│ • Mudanças cross-boundary precisam review │
│ • Packages compartilhados têm process claro │
│ │
└─────────────────────────────────────────────────────────────┘
Branching e PRs
ESTRATÉGIA DE BRANCHING:
┌─────────────────────────────────────────────────────────────┐
│ │
│ TRUNK-BASED (Recomendado): │
│ ────────────────────────── │
│ • main = sempre deployável │
│ • Feature branches curtas (< 1 dia) │
│ • Merge frequente │
│ • Feature flags para WIP │
│ │
│ POR QUE TRUNK-BASED: │
│ ───────────────────── │
│ • Evita merge hell │
│ • Feedback rápido │
│ • Monorepo + branches longas = dor │
│ │
│ PRS EM MONOREPO: │
│ ──────────────── │
│ • PRs pequenas e focadas │
│ • Uma área de ownership por PR idealmente │
│ • CI roda apenas testes afetados │
│ • CODEOWNERS para review automático │
│ │
└─────────────────────────────────────────────────────────────┘
Ferramentas Recomendadas
Stack de Ferramentas
FERRAMENTAS DE MONOREPO:
┌─────────────────────────────────────────────────────────────┐
│ │
│ NX: │
│ ──── │
│ • Completo e maduro │
│ • Detecção de afetados │
│ • Caching remoto (Nx Cloud) │
│ • Generators para scaffolding │
│ • Multi-linguagem │
│ │
│ TURBOREPO: │
│ ────────── │
│ • Simples e rápido │
│ • Caching local e remoto │
│ • Zero config básico │
│ • Adquirido pela Vercel │
│ │
│ PNPM WORKSPACES: │
│ ──────────────── │
│ • Package manager com workspaces │
│ • Symlinking eficiente │
│ • Estrito por padrão │
│ • Combina com Nx/Turborepo │
│ │
│ RECOMENDAÇÃO: │
│ ────────────── │
│ • Projetos JS/TS: pnpm + Turborepo ou Nx │
│ • Multi-linguagem: Nx ou Bazel │
│ • Começo simples: pnpm workspaces │
│ │
└─────────────────────────────────────────────────────────────┘
Melhores Práticas
Checklist de Implementação
CHECKLIST DE MONOREPO
═════════════════════
ESTRUTURA:
☐ Estrutura de pastas clara (apps/packages)
☐ Naming conventions definidas
☐ CODEOWNERS configurado
☐ README em cada pacote
BUILD:
☐ Builds incrementais configurados
☐ Caching remoto ativado
☐ CI otimizado para affected
☐ Tempo de build aceitável
DEPENDÊNCIAS:
☐ Workspace protocol usado
☐ Sem dependências circulares
☐ Política de versão externa clara
☐ Updates automatizados configurados
PROCESSO:
☐ Trunk-based development
☐ PRs pequenas
☐ Review process claro
☐ Documentação atualizada
Monorepos bem gerenciados aceleram desenvolvimento através de compartilhamento e consistência—mal gerenciados criam atrito e lentidão.