Monorepos centralizam todas as bases de código em um único repositório, permitindo mudanças cruzadas de serviço de forma atômica, gerenciamento centralizado de dependências e ferramentas consistentes. Eles são ideais quando as equipes precisam de coordenação apertada e práticas compartilhadas. Já os polyrepos isolam serviços em repositórios separados para implantações independentes, pilhas de tecnologia variadas e limites de propriedade simplificados, sendo ideais para equipes que operam de forma autônoma.

Ao escolher entre monorepos e polyrepos, a decisão certa depende de se você está otimizando para integração ou independência. Monorepos consolidam todos os serviços e bibliotecas em um único repositório versionado, permitindo mudanças atômicas em múltiplos pacotes ou serviços. Polyrepos, por outro lado, reforçam limites no nível do repositório, permitindo que cada serviço, biblioteca ou aplicativo viva de forma isolada.

Estrutura de repositório e limites de propriedade

Monorepos facilitam o gerenciamento de dependências e a versionagem, enquanto polyrepos exigem que bibliotecas compartilhadas sejam publicadas em um registro de pacotes. Monorepos permitem pipelines CI/CD que beneficiam de ferramentas que suportam a detecção de mudanças, enquanto polyrepos utilizam pipelines independentes.

Pipeline CI/CD

Monorepos permitem revisões de código coordenadas e refatorações, enquanto polyrepos tornam o processo mais lento, já que cada mudança deve ser acompanhada em repositórios separados. Monorepos centralizam ferramentas e sistemas de construção, enquanto polyrepos são mais rápidos de clonar e entender individualmente.

Escolhendo com base na coordenação e autonomia

Se suas equipes frequentemente fazem mudanças cruzadas de serviço, dependem de bibliotecas compartilhadas, ou precisam de coordenação apertada para lançamentos de funcionalidades, os monorepos eliminam o atrito. Se suas equipes são independentes, publicam no próprio ritmo, e valorizam o desacoplamento sobre a integração apertada, os polyrepos são uma escolha melhor.

Exemplo de arquitetura Monorepo

repo/
├── apps/
│   ├── api/
│   │   ├── src/
│   │   └── package.json
│   ├── admin/
│   │   ├── src/
│   │   └── package.json
│   └── web/
│       ├── src/
│       └── package.json
├── packages/
│   ├── ui/
│   │   ├── components/
│   │   └── package.json
│   └── config/
│       ├── eslint/
│       └── tsconfig/
├── .github/workflows/ci.yml
├── turbo.json
├── pnpm-workspace.yaml
└── package.json

No exemplo acima, a resolução de dependências é gerenciada através de pnpm workspaces. As bibliotecas internas são vinculadas automaticamente. A orquestração de construção e teste é feita via TurboRepo, que detecta mudanças e comanda escopos, enquanto a propriedade do código é aplicada via CODEOWNERS e diretórios com escopo em apps/. Ferramentas compartilhadas vivem em packages/config.

Exemplo de arquitetura Polyrepo

Cada serviço é seu próprio repositório Git com um pipeline CI separado. Bibliotecas internas são publicadas em um registro (por exemplo, npm ou GitHub Packages).

Repositório: api-service

api-service/
├── src/
├── package.json
├── .github/workflows/ci.yml
└── .env

Repositório: web-client

web-client/
├── src/
├── package.json
├── .github/workflows/ci.yml
└── .env

Repositório: shared-ui

shared-ui/
├── components/
├── package.json
└── .github/workflows/publish.yml

Neste código, shared-ui é versionado e publicado para o npm ou um registro privado em cada merge main. api-service e web-client instalam @org/shared-ui@^1.2.0 via npm install. Cada repositório executa seu próprio pipeline, e PRs são revisados e mesclados independentemente, enquanto lançamentos são rastreados usando tags e changelogs em cada repositório.

Conclusão

A decisão entre monorepos e polyrepos depende de se você está otimizando para a escala de serviços ou a velocidade de autonomia. Uma configuração de monorepo compensa quando a coordenação entre equipes é alta e a integração apertada entre serviços ou bibliotecas é crítica. Polyrepos funcionam melhor quando os serviços evoluem independentemente, e o overhead de coordenação deve ser evitado.