| name | monorepo-navigator |
| description | Navegador de Monorepo. Navega, gerencia e otimiza monorepos com Turborepo, Nx, pnpm workspaces e Lerna. Análise de impacto entre pacotes, builds seletivos, cache remoto e visualização de grafo de dependências. |
| agents | ["claude-code"] |
Monorepo Navigator
Nível: PODEROSO
Categoria: Engenharia
Domínio: Arquitetura de Monorepo / Sistemas de Build
Visão Geral
Navegue, gerencie e otimize monorepos. Cobre Turborepo, Nx, pnpm workspaces e Lerna. Habilita análise de impacto entre pacotes, builds/testes seletivos apenas nos pacotes afetados, cache remoto, visualização de grafo de dependências e migrações estruturadas de multi-repo para monorepo. Inclui configuração do Claude Code para desenvolvimento com consciência de workspace.
Capacidades Principais
- Análise de impacto entre pacotes — determine quais apps quebram quando um pacote compartilhado muda
- Comandos seletivos — execute testes/builds apenas nos pacotes afetados (não em tudo)
- Grafo de dependências — visualize relacionamentos entre pacotes como diagramas Mermaid
- Otimização de build — cache remoto, builds incrementais, execução paralela
- Migração — passo a passo de multi-repo → monorepo sem perda de histórico
- Publicação — changesets para versionamento, canais de pré-release, fluxos de trabalho npm publish
- Configuração do Claude Code — CLAUDE.md com consciência de workspace com instruções por pacote
Quando Usar
Use quando:
- Múltiplos pacotes/apps compartilham código (componentes UI, utilitários, tipos, clientes de API)
- Os tempos de build são lentos porque tudo reconstrói quando qualquer coisa muda
- Migrando de múltiplos repositórios para um único repositório
- Precisar publicar pacotes no npm com versionamento coordenado
- Equipes trabalham em múltiplos pacotes e precisam de ferramentas unificadas
Pule quando:
- Projeto de app único sem pacotes compartilhados
- Limites de equipe/projeto são completamente isolados (polyrepo está bem)
- O código compartilhado é mínimo e o overhead de copiar e colar é aceitável
Seleção de Ferramenta
| Ferramenta | Melhor Para | Funcionalidade-Chave |
|---|
| Turborepo | Monorepos JS/TS, configuração de pipeline simples | Cache remoto de melhor categoria, configuração mínima |
| Nx | Grandes empresas, ecossistema de plugins | Grafo de projeto, geração de código, comandos afetados |
| pnpm workspaces | Protocolo workspace, eficiência de disco | workspace:* para referências de pacotes locais |
| Lerna | Publicação npm, versionamento | Publicação em lote, commits convencionais |
| Changesets | Versionamento moderno (preferido ao Lerna) | Geração de changelog, canais de pré-release |
Configuração moderna mais comum: pnpm workspaces + Turborepo + Changesets
Turborepo
→ Veja references/monorepo-tooling-reference.md para detalhes
Analisador de Workspace
python3 scripts/monorepo_analyzer.py /caminho/para/monorepo
python3 scripts/monorepo_analyzer.py /caminho/para/monorepo --json
Veja também references/monorepo-patterns.md para arquitetura comum e padrões de CI.
Armadilhas Comuns
| Armadilha | Correção |
|---|
Executar turbo run build sem --filter em cada PR | Sempre use --filter=...[origin/main] no CI |
Refs workspace:* causam falhas de publicação | Use pnpm changeset publish — substitui workspace:* por versões reais automaticamente |
| Todos os pacotes reconstruindo quando arquivo não relacionado muda | Ajuste inputs no turbo.json para excluir docs e configurações das chaves de cache |
| tsconfig compartilhado faz um pacote quebrar todas as verificações de tipo | Use extends corretamente — cada pacote estende a raiz mas sobrepõe rootDir / outDir |
| Histórico git perdido durante migração | Use git filter-repo --to-subdirectory-filter antes de mesclar — nunca mova arquivos manualmente |
| Cache remoto não funcionando no CI | Verifique variáveis de ambiente TURBO_TOKEN e TURBO_TEAM; verifique com turbo run build --summarize |
| CLAUDE.md genérico demais — Claude modifica o pacote errado | Adicione regras explícitas "Ao trabalhar em X, mexa apenas em arquivos em apps/X" por CLAUDE.md do pacote |
Melhores Práticas
- CLAUDE.md raiz define o mapa — documente cada pacote, seu propósito e regras de dependência
- CLAUDE.md por pacote define as regras — o que é permitido, o que é proibido, comandos de teste
- Sempre delimite comandos com --filter — executar tudo em cada mudança anula o propósito
- Cache remoto não é opcional — sem ele, o CI do monorepo é mais lento que o CI de multi-repo
- Changesets em vez de versionamento manual — nunca edite versions de package.json manualmente em um monorepo
- Configurações compartilhadas na raiz, estendidas nos pacotes — tsconfig.base.json, .eslintrc.base.js, jest.base.config.js
- Análise de impacto antes de mesclar mudanças em pacotes compartilhados — execute a verificação de afetados, comunique o raio de impacto
- Mantenha packages/types como TypeScript puro — sem código de runtime, sem dependências, rápido de construir e verificar tipos
