Monorepo não é bala de prata. É uma decisão de arquitetura com trade-offs claros que dependem do tamanho e maturidade do time, não da popularidade da abordagem.
- O que monorepo resolve bem
- O que monorepo complica
- A pergunta certa
Monorepo virou assunto recorrente depois que empresas como Google, Meta e Vercel tornaram públicas suas estruturas de repositório. O raciocínio por trás da adoção é sedutor: código compartilhado em um lugar só, mudanças atômicas entre projetos, consistência de dependências.
O problema é que a maioria das empresas que adotam monorepo não tem as condições que tornam monorepo vantajoso nas empresas que o popularizaram.
O que monorepo resolve bem
Quando múltiplos projetos compartilham código — um design system, uma biblioteca de utilitários, tipos TypeScript compartilhados — monorepo elimina a dança de publicar pacotes, atualizar versões e sincronizar mudanças entre repositórios separados.
Em times onde front-end e back-end de um mesmo produto são desenvolvidos juntos, monorepo permite mudanças de API e interface na mesma pull request, com o CI validando ambos simultaneamente.
Esses benefícios são reais. Mas pressupõem que o time tem disciplina para manter o repositório organizado e ferramentas adequadas para lidar com builds incrementais em um repositório grande.
O que monorepo complica
Em times pequenos ou em projetos independentes sem código compartilhado, monorepo adiciona complexidade sem retorno proporcional.
A configuração de ferramentas como Turborepo, Nx ou Bazel tem curva de aprendizado real. CI torna-se mais complexo — é preciso garantir que apenas os projetos afetados por uma mudança sejam testados e deployados. Onboarding de novos desenvolvedores fica mais lento quando o repositório tem dezenas de projetos misturados.
A pergunta certa
A decisão não é “monorepo é boa prática?” — é “qual problema estou tentando resolver?”. Se a resposta é “compartilhar código entre projetos com versionamento controlado”, monorepo pode ser a resposta certa. Se a resposta é “queremos centralizar tudo em um lugar”, isso é organização, não arquitetura, e pode ser resolvido de formas mais simples.
Adotar monorepo porque é o que grandes empresas fazem é o mesmo erro de adotar microserviços porque é o que grandes empresas fazem. A escala do problema precisa justificar a complexidade da solução.
