Monorepo descomplicado: benefícios, desafios e boas práticas

Você está trabalhando em um projeto. O frontend está em um repositório, o backend em outro e as bibliotecas compartilhadas em um terceiro. Aí você fica alternando entre repos e torcendo para que as versões não se desencontrem.

Agora imagine tudo em um só lugar. Um único repo para todos os seus projetos, código compartilhado que atualiza na hora e mudanças que se propagam com um único commit. 

Monorepos tornam isso possível. É por isso que muitas big techs também usam, como: 

• o Google construiu o Piper com automação em larga escala
• a Meta escalou o Mercurial
• a Microsoft roda o Windows em um monorepo Git com VFS for Git
• a Uber chegou a sair do mono > ir para multi > e voltar para mono quando as ferramentas evoluíram

Neste guia, você vai entender o que é um monorepo, como ele se compara a polyrepos e os principais benefícios, desafios e boas práticas que valem a pena conhecer. 

O que é um monorepo?

Monorepo (repositório monolítico) significa um único repositório. Em um monorepo, todos os seus projetos diferentes ficam no mesmo lugar, em vez de estarem espalhados por vários repositórios. 

Mesmo lado a lado, os projetos continuam independentes. Ou seja, você pode construir, testar e implantar cada um separadamente — e ainda aproveitar o benefício de manter tudo reunido em um único ponto.

Mas vale notar: um aplicativo monolítico e um monorepo não são a mesma coisa:  

• Aplicação monolítica (monolito) é um único software construído e executado como uma unidade, geralmente sobre o mesmo conjunto de dados. Ela pode estar dentro de um monorepo (como apenas mais um dos projetos).
• Monorepo armazena e gerencia o código de forma que muitos projetos convivam no mesmo repo, mas sigam independentes entre si. 

Um monorepo não é um app monolítico. Na prática, monorepos costumam funcionar muito bem com microsserviços, porque cada serviço pode viver no mesmo repo e continuar independente.

A ideia de monorepo não é nova. 

No início dos anos 2000, grandes empresas de tecnologia começaram a adotar uma abordagem de “código-base compartilhado”. A lógica era simples: em vez de espalhar o código por vários repos, colocar tudo em um só lugar para facilitar a colaboração.

Desde então, big techs como Google, Meta, Microsoft, Airbnb, Twitter (X), Uber e Pinterest adotaram monorepos para administrar seus códigos grandes e em rápida evolução.

Monorepo vs. polyrepo

O oposto de um monorepo é um polyrepo (multirepo). Vamos ver como eles se diferenciam.  

Polyrepo

Um polyrepo, também chamado de multirepo, é quando cada projeto tem seu próprio repositório separado. 

Por exemplo, o código do frontend pode estar em um repo, o backend em outro e as bibliotecas compartilhadas em um terceiro. Cada repositório é gerenciado de forma independente, com suas próprias dependências e fluxos de trabalho.

Monorepo vs. polyrepo. Imagem do autor.

Um rápido olhar sobre as principais diferenças 

Vamos ver quais são as principais diferenças entre monorepos e polyrepos: 

Benefícios de um monorepo

Monorepos trazem muitos benefícios. Aqui vão alguns: 

Mais colaboração e visibilidade

Com todo o código em um só lugar, todo mundo enxerga o que está acontecendo. Você pode explorar outros projetos, aprender com eles ou até dar uma força quando necessário. 

Isso torna o trabalho em equipe mais fluido, aproxima times diferentes e reduz silos.

Gestão de dependências simplificada 

Se projetos diferentes usam as mesmas bibliotecas, mas mantêm versões próprias, a bagunça aparece rápido. 

Por exemplo, um projeto usa uma versão antiga e outro, uma mais nova. Isso pode dificultar a execução do código e fazer você perder tempo corrigindo o mesmo problema em mais de um lugar.

Num monorepo, o código compartilhado fica em um único local. Você atualiza uma vez e todo projeto recebe a correção na hora. Não precisa correr atrás de desencontros de versão ou lidar com conflitos entre versões diferentes.

Commits atômicos e refatoração mais fácil 

Às vezes, você precisa fazer uma mudança que afeta mais de um projeto. Por exemplo, atualizar uma biblioteca compartilhada. Com um monorepo, dá para atualizar esse código e aplicar as correções a todos os projetos em um único commit. 

Assim, todos os projetos ficam em sincronia e você evita quebrar outras partes sem querer. 

Ferramentas e processos consistentes

Com um repo, existe um jeito padrão de buildar, testar e fazer deploy. Você não precisa decorar setups diferentes para cada projeto. Isso facilita a entrada de novos membros sem confusão. 

Iteração mais rápida para certos fluxos

Se dois ou mais projetos dependem do mesmo código, como uma biblioteca ou utilitário compartilhado, você não precisa atualizar cada projeto separadamente em repos distintos. 

Num monorepo, você atualiza o código uma vez e todos os projetos daquele repositório recebem a mudança imediatamente. Em vez de alternar entre repos, você altera em um ponto e vê o impacto em todos ao mesmo tempo.

Isso ajuda em várias situações do dia a dia: 

• Ao refatorar código compartilhado, você atualiza a biblioteca e todo serviço que depende dela recebe a atualização na hora. 
• Ao lançar uma feature que toca mais de um app, dá para liberar tudo junto em vez de coordenar entre repos diferentes. 
• Até seus pipelines de CI/CD ficam mais simples, porque builds e testes rodam contra a mesma base de código, sem duplicação.

Tudo isso reduz idas e vindas, diminui trocas de contexto e encurta ciclos de feedback. Resultado: você itera mais rápido, sem sobrecarga extra.

Desafios de um monorepo

Monorepos trazem muitos ganhos, mas também alguns desafios. Os principais são:

Questões de escalabilidade e performance 

Conforme o repo cresce, tarefas do dia a dia como clonar, buscar ou até abrir no editor começam a ficar lentas. Por quê? Porque o Git originalmente não foi feito para lidar com bases de código gigantes. Por isso, empresas grandes sentem o peso com frequência.

Builds e testes mais longos

Como todos os projetos estão no mesmo lugar, uma pequena mudança pode disparar muito trabalho extra no pipeline de CI/CD. Com isso, desenvolvedores acabam esperando builds ou suítes de testes terminarem antes de poder fazer merge ou liberar código. 

Com o tempo, esses atrasos podem gerar problemas adicionais, como bloquear outras tarefas e dificultar implementar mudanças pequenas e frequentes.

Veja o caso da Uber: quando o monorepo em Go atingiu milhões de linhas de código, alguns engenheiros esperavam horas pelos builds e validações antes de fazer merge. 

Depois, eles aceleraram com ferramentas como Bazel e filas de build personalizadas. Ainda assim, isso mostra como o CI pode virar gargalo rápido quando todos os projetos compartilham um único repositório.

Risco de quebrar a branch principal 

A main é a branch padrão no Git onde vive a versão estável mais recente do seu código. Num monorepo, todo mundo trabalha a partir dessa branch compartilhada; se uma mudança a quebrar, todo o time (ou empresa) pode ficar bloqueado até o conserto.

Pegue o Airbnb como exemplo. Eles adotaram um deployment democrático (qualquer engenheiro podia testar seu trabalho e colocar em produção sem esperar um release manager). 

Parecia rápido no começo, mas conforme a empresa cresceu, ficou difícil administrar tudo porque o código estava em um único e grande monorepositório. As pessoas colocavam mudanças em produção ao mesmo tempo, updates colidiam e ficava mais difícil achar a causa dos problemas.

Controle de acesso e segurança

É difícil limitar acesso em um monorepo porque todo o código, arquivos de configuração, scripts de build e outros recursos ficam juntos. Por padrão, todo dev com acesso ao repo geralmente consegue ver e modificar todos esses componentes. 

Isso é ótimo para colaboração aberta, mas complica quando certas partes — como chaves de segurança, scripts de deploy ou algoritmos proprietários — exigem permissões mais rígidas.

Por exemplo, uma empresa pode manter o código do site no mesmo monorepo. Desenvolvedores do site não precisam necessariamente de credenciais de servidor de produção, mas, como tudo vive no mesmo lugar, pode ser difícil evitar que vejam ou editem esses arquivos sensíveis por engano.

Curva de aprendizado para novos devs 

Para quem está chegando, um repo enorme com vários projetos pode ser intimidante. Por quê? Porque há muitos arquivos e pastas, e fica difícil saber por onde começar ou o que é relevante para o trabalho. 

A pessoa também precisa aprender a estrutura do projeto, as ferramentas e as dependências antes de rodar builds com segurança ou fazer mudanças — o que pode desacelerar o início até ganhar familiaridade.

Boas práticas para gestão de monorepo

Para garantir que um monorepo funcione sem atritos, siga estas recomendações:

• Mantenha o repo organizado de forma lógica. Agrupe projetos relacionados, use nomes claros e facilite encontrar o que é preciso.
• Evite branches de longa duração. Experimente trunk-based development, fazendo merges frequentes na main. Isso mantém o repo limpo e reduz conflitos. 
• Fixe dependências em versões específicas para manter todo mundo em sincronia. Atualize-as no repo inteiro de uma vez para evitar desencontros. 
• Use ferramentas modernas de build como Bazel, Buck, Nx, Pants, Rush ou Lerna para acelerar builds e lidar com a complexidade de repos grandes. 
• Não rebuildar ou retestar o repo inteiro se só uma parte mudou. Use builds diferenciais e testes direcionados para economizar tempo e dar feedback mais rápido aos devs. 
• Configure Git CODEOWNERS na sua plataforma de VCS (por exemplo, GitHub/GitLab) para proteger áreas sensíveis, como scripts de deploy ou arquivos de configuração, e exigir revisão dos times responsáveis.

Ferramentas populares para gerenciar monorepos

Um monorepo pode ficar complexo conforme os projetos crescem. Para simplificar, surgiram diversas ferramentas que ajudam com builds, dependências e organização.  

Aqui estão algumas das mais usadas:

Bazel 

Bazel é um sistema de build open source criado no Google para lidar com bases de código muito grandes e complexas. 

Alguns destaques:

• Builds rápidos: Reconstrói apenas o que mudou, com cache avançado, análise otimizada de dependências e execução paralela.
• Suporte multilíngue: Funciona em diferentes plataformas e linguagens, incluindo Java, C++, Go, Android e iOS, além de Windows, macOS e Linux.
• Escala com facilidade: Lida com monorepos massivos e também com múltiplos repositórios, atendendo organizações de qualquer porte.
• Extensível: Permite adicionar novas linguagens e plataformas via sistema de extensões, apoiado por uma comunidade em crescimento.

Bazel é usado por empresas como Google, Stripe e Dropbox para buildar e testar infraestrutura e aplicações críticas.

Nx

Nx é um toolkit open source para gerenciar monorepos e é especialmente popular em JavaScript e TypeScript, com forte suporte a frameworks como React, Angular, Vue e NestJS. Ele ajuda times a organizar vários apps e bibliotecas em um só lugar, mantendo builds e testes rápidos. 

Alguns destaques: 

• Orquestrador inteligente: Entende as dependências entre partes do código e executa só o necessário, evitando desperdício.
• Funciona com o que você já tem: Roda scripts existentes, como tarefas npm ou Gradle, sem exigir mudanças no setup.
• Nx Cloud: Acelera o ciclo de desenvolvimento com cache remoto, CI mais rápido e ferramentas que ajudam a detectar e corrigir problemas automaticamente.
• Ferramentas extras: Recursos como o Nx Console oferecem autocomplete, grafo visual de projetos e formas fáceis de gerenciar tarefas.

Lerna

Lerna é uma das ferramentas mais antigas e confiáveis para gerenciar monorepos de JavaScript e TypeScript. Ela facilita organizar vários pacotes em um único repositório e ajuda a buildar, testar e publicá-los.

Inclusive, projetos bem conhecidos como Create React App, Jest e NestJS já usaram Lerna para gerenciar seus pacotes. 

Alguns destaques: 

• Builds inteligentes: Evita repetir trabalho reutilizando resultados em cache em vez de rebuildar o mesmo código.
• Execução rápida: Tarefas rodam em paralelo, respeitando a ordem das dependências.
• Cache distribuído: Resultados de build podem ser compartilhados entre devs e sistemas de CI, reduzindo tempos de build.
• Publicação de pacotes: Simplifica publicar no npm com versionamento compartilhado ou independente.
• Escalonamento: Espalha workloads entre várias máquinas sem configuração extra.
• Visualização: Inclui ferramentas para mostrar como projetos e dependências se conectam no repo.
• Pouca configuração: Exige pouca configuração, permitindo manter seus scripts npm e executá-los mais rápido.

Pants

Pants é um sistema de build rápido e fácil de usar, que funciona bem para monorepos de diversos tamanhos. Começou focado em Python e hoje também suporta Go, Java, Scala, Kotlin, Shell e Docker, com mais linguagens chegando. 

Por isso é amplamente utilizado e confiável para empresas como Coinbase, IBM, Slack, Salesforce e Orca Security, além de muitos times menores.

Alguns destaques:

• Fácil de adotar: Requer configuração mínima e infere automaticamente a maior parte das informações de build, reduzindo boilerplate.
• Builds seguros: Suporta múltiplas resoluções de dependência e lockfiles, criando builds reprodutíveis mais resistentes a ataques na cadeia de suprimentos.
• Flexível: Opera no nível de arquivo, lidando com estruturas de dependência complexas sem impor modularidade rígida.
• Extensível: Oferece sistema de plugins em Python para personalizar conforme as necessidades do time.
• Ciente do Git: Detecta mudanças entre branches e executa apenas os testes ou builds afetados.

Rush 

Rush é uma ferramenta de monorepo pensada para projetos JavaScript que precisam gerenciar múltiplos pacotes em um único repositório.

Alguns destaques: 

• Feito para escalar: Suporta builds paralelos, incrementais e distribuídos para manter repositórios enormes eficientes.

• Coordenação de times: Mantém versões de dependências consistentes, revisa novos pacotes antes de incluí-los e suporta versionamento compartilhado e independente.
• Instalações confiáveis: Suporta pnpm (recomendado), npm e Yarn para instalações previsíveis.
• Ferramenta tudo-em-um: Centraliza instalação, linking, builds, publicação, versionamento e changelogs.

Rush é open source e confiável, usado por produtos como Azure SDK, HBO Max, OneDrive, SharePoint, Office 365 e Wix.

Turborepo

Turborepo é um sistema de build de alta performance que torna monorepos de JavaScript e TypeScript mais rápidos e fáceis de gerenciar. Ele foca em resolver problemas clássicos de escala quando vários apps e pacotes convivem no mesmo repositório.

Alguns destaques:

• Cache remoto: Guarda resultados de builds e testes para que o mesmo trabalho não rode duas vezes, reduzindo o tempo de CI.
• Agendamento de tarefas: Executa tarefas na ordem correta e em paralelo em todos os núcleos disponíveis para máxima velocidade.
• Adoção incremental: Pode ser adicionado a qualquer repo em minutos, usando scripts do package.json e funcionando com npm, Yarn ou PNPM.
• Clonagem leve: Permite clonar apenas as partes do monorepo de que o dev precisa, reduzindo o tempo de setup.
• Fluxos otimizados: Builda apenas o que mudou, mantendo ciclos de feedback rápidos.
• Experiência familiar: Funciona com workflows padrão de Git e não exige mudar como os times já gerenciam código.

Moon

Moon é uma ferramenta rápida de gestão de monorepo escrita em Rust. Suporta linguagens como JavaScript, TypeScript, Rust, Go e Ruby.

Alguns destaques:

• Velocidade: Usa cache inteligente e builds incrementais para rebuildar só o que mudou.
• Colaboração: Cache remoto compartilha resultados entre colegas e o CI.
• Multiplataforma: Roda em Linux, macOS e Windows.
• Grafo de projetos: Mapeia dependências para ajudar a organizar e escalar repos grandes.

Lage

Lage é um task runner criado para monorepos, com foco em velocidade e eficiência. Ajuda times a evitar rebuildar trabalho já feito.

Alguns destaques:

• Pula trabalho repetido: Reutiliza resultados localmente ou dos colegas, evitando builds duplicados.
• Setup rápido: Fácil de configurar e funciona em diversos ambientes.
• Caching: Suporta cache local ou armazenamento externo para acelerar pipelines de CI.
• Insights: Inclui ferramentas para perfilar builds e visualizar grafos de dependências.

Yarn workspaces

Yarn introduziu workspaces para facilitar o gerenciamento de projetos com vários pacotes dentro de um único repo (um monorepo). 

Alguns destaques:

• Sem instalações duplicadas: Dependências comuns são instaladas uma única vez na raiz, evitando inflar o node_modules em cada pacote.
• Link automático: Se um pacote depende de outro no mesmo repo, o Yarn faz o link para você.
• Um lockfile: Um único yarn.lock para o repo inteiro, mantendo versões consistentes entre os pacotes.

Quando usar um monorepo

Veja alguns cenários comuns em que um monorepo pode ser útil para você: 

Times de pequeno a médio porte com código compartilhado

Se o seu time é pequeno e muito código é reutilizado entre projetos, um monorepo pode economizar tempo. Todo mundo trabalha no mesmo lugar e as bibliotecas compartilhadas ficam em sincronia sem esforço extra. É ganho dos dois lados.  

Projetos com dependências muito interligadas

Quando seus projetos dependem fortemente uns dos outros, mantenha-os em um repo. Assim, as mudanças acontecem juntas em um único commit, sem malabarismo entre vários repos.

Organizações que buscam tooling e visibilidade unificados

Com um monorepo, você pode configurar um CI/CD unificado. Isso não significa ter um único pipeline para todos os projetos, mas sim otimizar para que só os builds e testes afetados por mudanças recentes rodem — economizando tempo e recursos.

Mas monorepos não são ideais para todos os casos. Se seus projetos são totalmente independentes ou se você precisa de controles de acesso rígidos (em que alguns times não devem ver partes específicas do código), polyrepos (múltiplos repos) podem ser a melhor escolha.

Colocando prós e contras na balança

Aqui vai um resumo rápido das vantagens e desvantagens dos monorepos:

Considerações finais

Um monorepo pode facilitar a colaboração, simplificar dependências e acelerar a iteração, mas também traz desafios reais de escala, performance e acesso. Adotar essa abordagem deve ser uma decisão estratégica baseada em como seus times se organizam, o quanto seus projetos dependem uns dos outros e se você está pronto para investir nas ferramentas certas.

Mas sem hábitos fortes de colaboração e ownership claro, nem o melhor setup de monorepo vai decolar. Se você está explorando esse caminho, vale reforçar seus fundamentos primeiro. O curso Software Engineering Principles in Python é um ótimo ponto de partida. Ele vai ajudar você a construir as práticas que fazem um monorepo dar certo.