Monorepo vs Polyrepo: A Escolha de Stack que Funciona

A questão monorepo vs polyrepo surge antes de cada novo projeto, e a resposta molda meses de setup de CI/CD, overhead de refatoração e controle de acesso de equipe. Para a maioria dos devs solo construindo um produto com código compartilhado, a escolha certa em 2026 é monorepo. Não porque é a moda do momento, mas porque elimina a cerimônia de publicação que polyrepos impõem no instante em que dois pacotes precisam conversar um com o outro. Se seus serviços são completamente independentes e genuinamente nunca compartilharão código, polyrepo é mais simples. Todo outro caso é contexto.

São 22h. Um novo projeto está tomando forma: uma API backend, um pacote de tipos TypeScript compartilhados e um dashboard frontend que inevitavelmente consumirá ambos. Duas abas abertas. O cursor está piscando.

A maioria dos posts sobre este tema é escrita para equipes de engenharia de vinte pessoas com um DevOps engineer dedicado que gosta de configurar Bazel. Este é para builders que precisam tomar a decisão antes do primeiro commit, porque reestruturar seis meses depois, quando você tem usuários reais e um pipeline de CI cuja mecânica seus músculos memorizam, é o tipo de coisa que mata o momentum de um side project para sempre.

O que um monorepo realmente te dá (não a versão do textbook)

O pitch padrão é "um repo, dependências compartilhadas, mudanças atômicas." Tudo isso é real. Mas a parte que realmente importa dia a dia para um builder solo é mais concreta: você não precisa publicar pacotes para usá-los localmente.

Em setup de polyrepo, se shared-utils precisa de uma correção que também afeta api-service, você publica uma nova versão de shared-utils, muda a dependência em api-service, aguarda o CI passar e depois faz deploy. Caso contrário, você cai nos hacks de npm link que funcionam até pararem de funcionar no meio do sprint. Em monorepo com workspaces, você muda o código e todo pacote que o importa vê a mudança imediatamente. Sem cerimônia de publicação.

Aqui está o que isso parece com pnpm workspaces, que adiciona overhead de configuração mínimo:

/packages
  /shared-types      ← importado direto por api e web
  /api
  /web
package.json         ← workspace root com campo "workspaces"

// api/package.json
{
  "dependencies": {
    "@myapp/shared-types": "workspace:*"
  }
}

Sem publicação. Sem bump de versão durante desenvolvimento. workspace:* resolve para o pacote local, e TypeScript project references te dão compilação incremental através do grafo inteiro.

O segundo benefício real: refatoração cross-package que chega em um PR. Renomear uma interface em shared-types? TypeScript te diz cada consumidor que quebrou, no mesmo codebase, na mesma sessão de editor. Em polyrepo, você a renomeia no repo A, publica uma nova versão e descobre o problema no repo B três dias depois quando um colega roda npm install e os tipos não batem com a runtime.

O terceiro benefício, que devs solo subestimam: um único lugar para configuração de tooling. Um .eslintrc, um prettier.config.js, um arquivo de workflow de CI. Economias pequenas por mudança, mas que se acumulam ao longo de meses de iteração.

Vale nomear o que um monorepo não te dá: não torna serviços menos acoplados. Se seus serviços são genuinamente independentes e você os coloca num monorepo mesmo assim, você adicionou overhead de coordenação sem retorno nele. Os benefícios do monorepo só se materializam quando os serviços realmente compartilham código ou precisam mudar juntos. A estrutura do repo deve refletir a estrutura de dependência, não impor uma.

Quando polyrepo merece seu lugar

Polyrepo não é um erro. É a escolha certa para situações específicas, e fingir o contrário é como você termina com um monorepo de 40 serviços que leva 25 minutos para clonar.

O caso mais claro: serviços com genuinamente diferentes dono, ciclos de release ou requisitos de conformidade. Se seu serviço de billing é PCI-scoped e seu site de marketing não é, manter em repositórios separados significa manter controle de acesso, audit logs e blast radius nitidamente separados. Isso não é overhead operacional. Isso é a feature.

Polyrepo também vence quando você está open-sourcando parte do seu codebase. Um repo público dedicado deixa contribuidores externos fazer fork e PR sem puxar sua infraestrutura privada para o escopo. O modelo de permissões por repositório do GitHub não te dá isolamento de acesso limpo por path em escala. Um repo separado lida com isso corretamente.

E para microserviços puros com tech stacks completamente distintos: um serviço Go e um app React Native que literalmente não compartilham nada no nível de código, um monorepo adiciona custo de coordenação sem entregar o benefício. Se não há pacotes compartilhados, não há nada para compartilhar.

A versão honesta disso: a maioria dos projetos indie que começam com polyrepo acabam se arrependendo, não porque polyrepo é má arquitetura, mas porque superestimaram quanto os parts se manteriam independentes. O frontend sempre precisa de um tipo do backend. O worker sempre precisa de um utilitário da API. Dois repos viram quatro PRs para cada feature.

O custo de CI/CD que ninguém menciona até bater na fatura

Monorepos têm um custo operacional real: se seu CI naivamente roda tudo em cada commit, você está pagando em tempo e dinheiro por builds e testes que não têm nada a ver com o que você mudou.

Faça push de um ajuste de CSS no pacote web. CI roda a suite inteira de testes para api, worker e shared-types. Isso são seis minutos de compute de GitHub Actions por uma mudança de cor. Em escala, isso vira filas de CI que bloqueiam toda sua equipe.

A solução existe, mas requer setup deliberado: ferramentas de orquestração de build que entendem seu grafo de dependência. Turborepo e Nx resolvem ambas. O turbo.json do Turborepo define um pipeline onde cada task roda apenas para pacotes com inputs alterados:

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "cache": true
    }
  }
}

Com remote caching habilitado (grátis na tier de Turborepo Cloud da Vercel para pequenas equipes), um cache hit num pacote inalterado é instantâneo, sem rebuild, sem retest. Para um dev solo num side project, isso mantém CI em menos de dois minutos na maioria dos pushes quando os artefatos de build estão quentes.

O custo: você precisa aprender Turborepo ou Nx antes de precisar, não depois. É mais ou menos meio dia de setup. Se você pula isso e deixa CI acumular gordura, o CI de monorepo vai desacelerar até o ponto onde você começar a questionar a escolha arquitetural inteira, e normalmente é aí que devs decidem que polyrepo era certo o tempo todo, quando o problema real era só um arquivo de configuração faltando.

Como ferramentas de programação IA mudaram a matemática desse debate

Até recentemente, um argumento genuíno para polyrepo era carga cognitiva: repos menores são mais fáceis de raciocinar porque estão isolados. Context-switch para um novo serviço, veja apenas o que é relevante para esse serviço. O argumento era legítimo.

Ferramentas de programação IA mudam esse cálculo. Quando você trabalha com Cursor, Claude Code ou GitHub Copilot, a ferramenta trabalha com seu codebase completo em contexto. Ela vê dependências cross-service, entende qual interface é consumida por qual serviço e pode rastrear um campo renomeado através de cada consumidor sem você manter o modelo mental você mesmo. O argumento "repo isolado é mais fácil de entender" enfraquece significativamente quando seu assistente IA mantém o grafo inteiro de dependência em contexto de qualquer forma.

Um exemplo concreto: em setup de polyrepo, se você pedir a um assistente IA para refatorar um endpoint de API que também afeta um tipo compartilhado, tipicamente ele não consegue ver ambos os repos numa sessão. Você está fazendo a coordenação manualmente, que é exatamente o overhead que um monorepo deveria eliminar. Em monorepo, a mesma refatoração é uma conversa.

Isso não inverte a decisão inteira. Mas remove uma das justificativas históricas para polyrepo para pequenas equipes e devs solo, e inclina o default um pouco mais para monorepo quando o código é genuinamente acoplado.

Três sinais que significam que você deveria separar o repo agora

Você começou com um monorepo. Bom. Mas aqui estão os sinais concretos que a separação se tornou a escolha certa:

Controle de acesso está se tornando crítico. Um contractor precisa de acesso ao frontend, não ao backend. Uma equipe de integração de parceiro precisa ler seu schema de API mas nada proprietário. GitHub Codeowners pode restringir quem pode revisar quais paths, mas não restringe acesso de leitura. Se isolamento de leitura importa para conformidade ou segurança, repos separados são a resposta limpa. Codeowners gymnastics nunca substitui integralmente permissões no nível de repositório.

CI failures em um serviço estão bloqueando deployment num serviço não-relacionado. Se um teste quebrado em payment-service está barrando um hotfix que você precisa fazer deploy em marketing-site, seu monorepo está criando acoplamento que seu codebase não tem. Ou a configuração de build precisa ser consertada (task scoping com Turborepo vai resolver isso), ou os dois serviços genuinamente não pertencem no mesmo repo.

Uma parte vai open-source e uma não. Este é o caso de separação mais limpo. Extraia a peça open-source para seu próprio repo público. Código misto público/privado em monorepo de GitHub é genuinamente doloroso: você precisaria de uma organização separada ou um processo de poda manual que cria overhead de manutenção permanente.

O setup prático que a maioria dos builders adota

A resposta que a maioria dos devs experientes se estabelecem: um monorepo por domínio de produto, não "um monorepo para tudo que você já construiu" e não "um repo por pacote."

Se você está construindo um SaaS com um frontend web, uma API e uma biblioteca de tipos compartilhados, aquilo é um produto. Mantenha num monorepo. Se você também mantém um utilitário CLI open-source que outros projetos usam, aquilo é um repo diferente com audiência e ciclo de release diferentes.

O erro é tratar a escolha monorepo/polyrepo como ideológica. Não é "times monorepo" versus "times polyrepo." É uma decisão estrutural baseada em três perguntas: Qual é o grafo de dependência entre seus serviços? Quem precisa acessar o quê, e isolamento importa? Qual é sua tolerância para complexidade de setup de CI/CD?

Para side projects especificamente: comece com monorepo usando pnpm workspaces (npm workspaces também funcionam, só menos ergonômico). Adicione Turborepo apenas quando seu CI rotineiramente começar a bater 4+ minutos. Separe em um repo diferente apenas quando tiver uma razão concreta: open-source, controle de acesso, conformidade ou uma equipe parceira com cadência de release diferente. Não porque parece mais limpo arquiteturalmente.

O debate monorepo vs polyrepo é uma daquelas escolhas onde a resposta certa para a maioria dos devs solo é a mesma: comece simples, otimize quando o atrito específico aparece. O cursor ainda está piscando. Faça deploy do primeiro commit.