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
1---2name: monorepo-navigator3description: 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.4---56# Monorepo Navigator78**Nível:** PODEROSO9**Categoria:** Engenharia10**Domínio:** Arquitetura de Monorepo / Sistemas de Build1112---1314## Visão Geral1516Navegue, 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.1718---1920## Capacidades Principais2122- **Análise de impacto entre pacotes** — determine quais apps quebram quando um pacote compartilhado muda23- **Comandos seletivos** — execute testes/builds apenas nos pacotes afetados (não em tudo)24- **Grafo de dependências** — visualize relacionamentos entre pacotes como diagramas Mermaid25- **Otimização de build** — cache remoto, builds incrementais, execução paralela26- **Migração** — passo a passo de multi-repo → monorepo sem perda de histórico27- **Publicação** — changesets para versionamento, canais de pré-release, fluxos de trabalho npm publish28- **Configuração do Claude Code** — CLAUDE.md com consciência de workspace com instruções por pacote2930---3132## Quando Usar3334Use quando:35- Múltiplos pacotes/apps compartilham código (componentes UI, utilitários, tipos, clientes de API)36- Os tempos de build são lentos porque tudo reconstrói quando qualquer coisa muda37- Migrando de múltiplos repositórios para um único repositório38- Precisar publicar pacotes no npm com versionamento coordenado39- Equipes trabalham em múltiplos pacotes e precisam de ferramentas unificadas4041Pule quando:42- Projeto de app único sem pacotes compartilhados43- Limites de equipe/projeto são completamente isolados (polyrepo está bem)44- O código compartilhado é mínimo e o overhead de copiar e colar é aceitável4546---4748## Seleção de Ferramenta4950| Ferramenta | Melhor Para | Funcionalidade-Chave |51|---|---|---|52| **Turborepo** | Monorepos JS/TS, configuração de pipeline simples | Cache remoto de melhor categoria, configuração mínima |53| **Nx** | Grandes empresas, ecossistema de plugins | Grafo de projeto, geração de código, comandos afetados |54| **pnpm workspaces** | Protocolo workspace, eficiência de disco | `workspace:*` para referências de pacotes locais |55| **Lerna** | Publicação npm, versionamento | Publicação em lote, commits convencionais |56| **Changesets** | Versionamento moderno (preferido ao Lerna) | Geração de changelog, canais de pré-release |5758Configuração moderna mais comum: **pnpm workspaces + Turborepo + Changesets**5960---6162## Turborepo63→ Veja references/monorepo-tooling-reference.md para detalhes6465## Analisador de Workspace6667```bash68python3 scripts/monorepo_analyzer.py /caminho/para/monorepo69python3 scripts/monorepo_analyzer.py /caminho/para/monorepo --json70```7172Veja também `references/monorepo-patterns.md` para arquitetura comum e padrões de CI.7374## Armadilhas Comuns7576| Armadilha | Correção |77|---|---|78| Executar `turbo run build` sem `--filter` em cada PR | Sempre use `--filter=...[origin/main]` no CI |79| Refs `workspace:*` causam falhas de publicação | Use `pnpm changeset publish` — substitui `workspace:*` por versões reais automaticamente |80| 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 |81| 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` |82| Histórico git perdido durante migração | Use `git filter-repo --to-subdirectory-filter` antes de mesclar — nunca mova arquivos manualmente |83| Cache remoto não funcionando no CI | Verifique variáveis de ambiente TURBO_TOKEN e TURBO_TEAM; verifique com `turbo run build --summarize` |84| 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 |8586---8788## Melhores Práticas89901. **CLAUDE.md raiz define o mapa** — documente cada pacote, seu propósito e regras de dependência912. **CLAUDE.md por pacote define as regras** — o que é permitido, o que é proibido, comandos de teste923. **Sempre delimite comandos com --filter** — executar tudo em cada mudança anula o propósito934. **Cache remoto não é opcional** — sem ele, o CI do monorepo é mais lento que o CI de multi-repo945. **Changesets em vez de versionamento manual** — nunca edite versions de package.json manualmente em um monorepo956. **Configurações compartilhadas na raiz, estendidas nos pacotes** — tsconfig.base.json, .eslintrc.base.js, jest.base.config.js967. **Análise de impacto antes de mesclar mudanças em pacotes compartilhados** — execute a verificação de afetados, comunique o raio de impacto978. **Mantenha packages/types como TypeScript puro** — sem código de runtime, sem dependências, rápido de construir e verificar tipos
ricneves-ai