Monorepo vs polyrepo: welke keuze voor jouw engineeringteam

De keuze tussen monorepo vs polyrepo bepaalt hoe je engineeringteam samenwerkt en schaalt. Een monorepo wint wanneer teams regelmatig code delen en veranderingen coördineren via een gemeenschappelijk oppervlak; een polyrepo wint wanneer teams echt onafhankelijk zijn en zonder op elkaar te wachten deployeren. Alles daartussenin hangt af van hoe sterk gekoppeld je services eigenlijk zijn, en hoeveel coördinatieoverhead je bereid bent op te nemen. Dit artikel loopt door de werkelijke trade-offs.

De echte vraag gaat over koppeling, niet over het aantal repositories

De meeste monorepo versus polyrepo debatten beginnen met de verkeerde vraag. Het aantal repositories is niet het probleem. Het probleem is of je teams gelijktijdig moeten bewegen.

Als de veranderingen van Team A regelmatig vereisen dat Team B iets op dezelfde releasecyclus aanpast, heb je sterk gekoppeld werk. Één repository daarvoor is bijna altijd het schoonere antwoord. Als Team A en Team B op hun eigen schema's werken, verschillende delen van het systeem aanraken, en nooit op elkaar wachten, hebben aparte repositories echt zin.

Het slechtste mogelijke resultaat: twee aparte repositories voor code die nog steeds samen moet deployen. Je krijgt al de coördinatiekosten van een monorepo zonder de voordelen. Je teams eindigen ermee pull requests in repo A en repo B gelijktijdig in te dienen, hopend dat beide tegelijk CI passeren. Dit patroon komt verrassend vaak voor in organisaties die vroeg voor polyrepo kozen en hun services vervolgens interdependenter lieten worden dan oorspronkelijk gepland.

De eerste stap voordat je iets kiest is het tekenen van een eenvoudige afhankelijkheidskaart. Vermeld elke service of package die je bezit en teken pijlen waar de ene van de ander afhangt. Als de pijlen een dichte cluster vormen, hoort die cluster in één repository.

Waarom Google, Meta en Microsoft allemaal op monorepos uitkwamen op schaal

Google slaat het meeste van zijn code op in een enkel repository dat naar schatting meer dan 80 TB aan gegevens en 2 miljard regels code bevat. Meta en Microsoft doen hetzelfde voor hun kernproductoppervlakken. Dit is niet omdat grote bedrijven houden van complexiteit; het is omdat het synchroniseren van dependencies in honderden repositories op schaal een volledige engineeringprobleem wordt.

Een enkele API-wijziging in een gedeelde bibliotheek vereist wellicht gecoördineerde updates in 40 verschillende repositories. In een monorepo is dat één pull request. Één review. Één merge. Eén rollback als er iets misgaat.

Volgens onderzoek gepubliceerd door Sourcegraph gebruikt 63% van de bedrijven met 50 of meer developers nu een monorepo voor minstens een deel van hun codebase, een sterke stijging ten opzichte van cijfers van drie jaar eerder.

Het concrete voordeel dat het meeste uitmaakt: atomic commits. Wanneer een breking in je API ook frontend- en backend-updates vereist, laat een monorepo je alle drie de veranderingen in één PR landen, ze samen testen, en alle drie als een eenheid terugdraaien als iets misgaat. Met polyrepo open je drie aparte PRs, wacht je op drie aparte reviewcycli, en beheer je een venster waarin je services versies mismatch uitvoeren.

Één engineeringteam meldde over te gaan van incidentele deployments naar meer dan 40 app-releases per week na migratie van hun frontend-packages naar een Nx-monorepo. Angular-upgrades die eerder maanden duurden werden routinematige taken die teams zonder stopzetting van ander werk afhandelden.

De verborgen coördinatietax van polyrepo

Polyrepo heeft echte voordelen die het waard zijn serieus te nemen. Elk team bepaalt zijn eigen CI/CD-pipeline, zijn eigen releasetempo, zijn eigen toegangscontroles. Beveiligings- en complianceteams geven er vaak de voorkeur aan: toegang tot code kan per repository tot benoemde personeelsleden beperkt zijn, wat in gereglementeerde industrieën van belang is. Open-sourcecomponenten leven schoner in hun eigen openbare repositories zonder interne code bloot te stellen.

Voor teams die echt onafhankelijk zijn, zijn deze voordelen echt. Een klein servicesteam dat een datapipeline bezit die op zijn eigen schema draait en geen gedeelde code aanraakt heeft weinig aan het zitten in een groter monorepo.

Maar polyrepo-organisaties stapelen stilletjes kosten op die niet in de originele beslissing opdoken. Dependency-versiebeheer tussen repositories wordt zijn eigen discipline. Een gedeelde hulpprogrammabiblioteek wordt verouderd in sommige repositories terwijl andere actueel blijven. Iemand moet een compatibiliteitsmatrix onderhouden om alleen al te weten welke versie van welk bibliotheek met welke versie van welke service werkt.

Eén metriek waard om te kennen: mediane PR-cyclustijd in monorepos loopt rond de 19 uur, tegenover ongeveer 2 uur in polyrepos. PRs in monorepos zijn meestal groter omdat ze meer oppervlakken aanraken, wat review vertraagt. Maar wanneer een polyrepo-wijziging drie gecoördineerde PRs in drie repositories vereist om één feature te landen, overschrijdt de totale cyclustijd vaak het monorepo-cijfer; met het extra risico van gedeeltelijke merges die services in inconsistente toestanden achterlaten.

Het patroon dat teams verrast: "we begonnen met aparte repositories voor onafhankelijkheid, maar nu vereist elke release het openen van PRs op vier plaatsen." Op dat moment heb je het slechtste van beide werelden.

Buildtijden stopten rond 2024 als bepalende factor

De klassieke inzwering tegen monorepos was buildtijd. Als je repository 200 packages bevat en je wijzigt één bestand, wil je echt alle 200 opnieuw bouwen?

Dit argument verviel ergens rond 2022 tot 2024, afhankelijk van je stack.

Moderne buildtools gebruiken content-aware caching. Ze bouwen alleen opnieuw wat veranderd is, en slaan alles met identieke invoer over. Een wijziging in het payments-package triggert geen herbouw van design-system als niets in design-system veranderd is. GitHub Actions biedt 10 GB gratis cachegeheugen voordat je een betaalde remote-cacheoplossing nodig hebt.

Turborepo handelt de meeste JavaScript- en TypeScript-teams goed af tot ongeveer 20 packages. De configuratie is een enkel turbo.json, remote caching werkt gratis op Vercel of self-hosted, en de leerkromme is laag genoeg dat een team binnen een dag productief kan zijn.

Voorbij 20 packages, of wanneer de build meerdere talen overlapt, rechtvaardigt de meer gestructureerde aanpak van Nx meestal de steilere leerkromme. Nx voegt codegeneratie, automatische CI-distributie en fijnkorrelige afhankelijkheidstracering toe die steeds waardevol wordt naarmate de repository groeit.

Voor zeer grote organisaties met duizenden packages in meerdere talen is Bazel (Google's open-source buildsysteem) het enige systeem ontworpen voor die schaal. De instellingskosten zijn aanzienlijk en vereisen bijna altijd een dedicated platformtechniek-team.

Vier vragen die het debat voor je team beslechten

Er is geen universeel juist antwoord, maar er is een betrouwbaar raamwerk.

1. Delen je teams code die regelmatig verandert? Ja; een gedeeld designsysteem, een gedeelde API-clientbibliotheek, gedeelde authenticatielogica; een monorepo is bijna altijd de betere keuze. Het synchroniseren van een gedeelde bibliotheek in meerdere repositories vereist constant discipline en drifts bijna altijd.

2. Deployeren je teams onafhankelijk? Als Team A's service op dinsdag en Team B's op donderdag uitkomt zonder enige coördinatie nodig, verdient polyrepo zijn plaats. Als één service vrijgeven gelijktijdige vrijgave van een ander vereist, hoort die koppelingskost in de vergelijking thuis.

3. Hoeveel engineers raken deze codebase aan? Onder 20 engineers maakt de repository-structuur minder uit dan je denkt. Boven 50 beginnen de coördinatiekosten van polyrepo merkbaar op te stapelen. Boven 200 wordt het geval voor een monorepo zeer sterk, tenzij teams echt per product en technologie gesegmenteerd zijn.

4. Heb je beveiligings- of compliancevereisten die code per team isoleren? In gereglementeerde industrieën; financiën, gezondheidszorg, sommige overheidskontexten; moet toegang tot code wellicht tot benoemde personeelsleden beperkt zijn. Die beperking kan de andere antwoorden overschaduwen. Als harde codeisolatie een compliancevereiste is, is polyrepo geen keuze, het is een beperking.

Als je "ja" antwoordde op vraag 1 en "nee" op vraag 4, is een monorepo bijna zeker het juiste antwoord. Als je "nee" antwoordde op vraag 1 en "ja" op vraag 2, is polyrepo een verdedigbare keuze. Al het andere is een oordeel.

Wat meeste groeiende teams werkelijk belanden

Zeer weinig volgroeide engineeringorganisaties opereren aan beide uitersten. Het patroon dat het meest verschijnt: een monorepo voor het kernproduct (frontend, gedeelde bibliotheken, backend-services die van elkaar afhangen), en aparte repositories voor werkelijk onafhankelijke componenten.

Een datapipeline die op zijn eigen schema draait en geen code met het hoofdproduct deelt hoort buiten de monorepo. Een intern gereedschap onderhouden door een eenpersoonssteam hoort buiten. Een open-sourcebibliotheek die openbare zichtbaarheid nodig heeft hoort buiten.

Dit is geen compromis. Het is het juiste antwoord op een vraag die zelden een schoon binair antwoord heeft. Houd dingen samen die samen moeten bewegen. Scheid wat echt onafhankelijk is.

Het belangrijkste is om de beslissing opzettelijk te nemen, niet op afstand. De meeste teams die eindigen met polyrepo-verspreiding kozen het niet: ze begonnen met één service, daarna nog een, daarna nog een, en stopten nooit om te vragen of die services samen moesten wonen.

De tooling die elk voorstel werkelijk doet werken

Voor monorepos:

• Nx: sterkste featureset, goed voor polyglot builds en teams voorbij 20 packages. Hogere leerkromme maar schalen verder.

• Turborepo: eenvoudiger om te starten, uitstekend voor JS/TS-teams onder 20 packages. Native Vercel-caching of self-hosted opties.

• Bazel: voor zeer grote meertalige repositories op ondernemingsschaal. Aanzienlijke installatieninvestering vereist.

Voor polyrepos:

• Een versiebeheersdiscipline voor gedeelde bibliotheken is niet optioneel. Zonder semantic versioning en een consistent changelogproces wordt afhankelijkheidsdrift de norm binnen zes maanden.

• CI/CD-gereedschap dat cross-repo-pipelines triggert wanneer een gedeelde afhankelijkheid verandert. GitHub Actions ondersteunt dit via workflow_dispatch en repository_dispatch-events tussen repositories.

• Een afhankelijkheidsregister (npm private registry, GitHub Packages, Artifactory) om distributie van gedeelde packages te beheren.

De keuze van welke te gebruiken valt nog steeds terug op die vier vragen.