Monorepo vs Polyrepo: de juiste repostructuur

De monorepo polyrepo-discussie duikt op zodra een project begint te groeien. Houd je al je code in één Git-repository, of splits je elke service, elk pakket of elke app op in een eigen repo? Er is geen universeel "doe altijd dit"-antwoord; het hangt af van je teamgrootte, je deploymodel en je tooling. In dit artikel vergelijk ik beide benaderingen met concrete voorbeelden en laat ik je zien hoe je beslist welke het minste pijn doet in je eigen project.

De basis: wat zijn monorepo's en polyrepo's?

Een monorepo is één versiebeheer-repository die meerdere projecten, pakketten of services bevat. De frontend, backend, gedeelde bibliotheken en infrastructuurscripts komen allemaal mee met één git clone. Een typische indeling ziet er zo uit:

my-company/
├── apps/
│   ├── web/
│   └── admin/
├── packages/
│   ├── ui/
│   └── config/
└── services/
    └── api/

Een polyrepo (multi-repo) houdt een aparte Git-repository per onafhankelijke eenheid: company-web, company-api, company-ui-kit, enzovoort. Elke repo draagt zijn eigen versiebeheer, zijn eigen CI-pijplijn en zijn eigen toegangsrechten. Beide benaderingen worden al jaren in productie gebruikt; de echte vraag is welke bij jouw beperkingen past.

Waar monorepo's uitblinken

De grootste aantrekkingskracht van een monorepo is dat het één enkele bron van waarheid biedt. Wanneer je een gedeelde component wijzigt, kun je elke app die hem gebruikt in dezelfde commit bijwerken. Dat betekent atomaire wijzigingen:

• Consistente afhankelijkheden: alle projecten gebruiken dezelfde bibliotheekversies, dus "bij mij werkte het"-problemen nemen af.
• Makkelijk code delen: je importeert een gemeenschappelijk ui-pakket rechtstreeks, zonder een nieuwe repo te publiceren.
• Overkoepelende refactors: bij het hernoemen van een API-veld herstel je zowel de server als alle clients in één pull request.
• Zichtbaarheid: met alle code op één plek worden zoeken, navigeren en standaarden vastleggen eenvoudiger.

Voor sterk gekoppelde codebases die vaak samen veranderen, levert een monorepo doorgaans minder wrijving op.

Waar polyrepo's uitblinken

Polyrepo's leunen op duidelijke grenzen en onafhankelijkheid. Elk team bezit zijn eigen repo, zijn eigen releaseritme en zijn eigen deployschema. De voordelen zijn:

• Kleiner oppervlak: een ontwikkelaar kloont alleen de repo die hem aangaat, dus checkout en indexering blijven snel.
• Onafhankelijk versiebeheer: elke service tagt zijn eigen semantische versie; de release van het ene team wacht niet op het andere.
• Fijnmazige toegang: alleen bevoegde mensen bereiken de repo van een gevoelige service.
• Eenvoudige CI: de pijplijn van elke repo bouwt alleen die repo, zonder extra logica om uit te vinden "wat er is veranderd."

Voor services die echt onafhankelijk zijn, in verschillende talen geschreven of met verschillende levenscycli, stroomt een polyrepo vanzelf.

Schalen en de impact van tooling

Wat de vraag meestal beslist, is tooling. Naarmate een monorepo groeit, worden naïeve opstellingen traag: je wilt niet alles opnieuw bouwen bij elke commit. Daarom leunen monorepo's meestal op een taakuitvoerder. In het JavaScript/TypeScript-ecosysteem zijn turborepo, nx en pnpm workspaces gangbaar; ze bouwen alleen de getroffen pakketten en cachen de resultaten.

# pnpm workspace-definitie
# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

In een polyrepo verschuift het probleem: builds blijven eenvoudig, maar afhankelijkheidsbeheer wordt lastiger. Je moet de gedeelde bibliotheek publiceren naar een pakketregister (bijvoorbeeld een privé-npm-register, of een Composer/Packagist-opzet voor PHP) en daarna de versie verhogen in elke afnemende repo. Dat verhoogt het risico op versieverschil: repo A gebruikt misschien bibliotheek 2.1 terwijl repo B nog op 1.8 zit.

Welke moet je kiezen?

Een praktisch beslissingskader:

• Kies een monorepo als je een klein tot middelgroot team bent, je codebases sterk gekoppeld zijn, je vaak overkoepelende wijzigingen maakt en je bereid bent te investeren in een tool als nx of turborepo.
• Kies een polyrepo als je meerdere onafhankelijke teams hebt, je services in verschillende talen en levenscycli draaien, je strikte toegangsscheiding nodig hebt en je losse koppeling wilt via duidelijke API-contracten.

Er is een derde weg: een geleidelijke middenweg. Veel teams bundelen een paar gerelateerde services in één monorepo en houden volledig losstaande producten apart. Je hoeft niet "puur" te zijn; trek de grens op basis van hoe vaak de code samen verandert.

Veelgestelde vragen

Vertraagt een monorepo Git?

Dat kan bij zeer grote historie, maar voor de meeste projecten is het geen probleem. Als de repo echt enorm wordt, kun je een partial clone gebruiken met git clone --filter=blob:none of sparse-checkout om alleen de mappen op te halen die je nodig hebt.

Heb ik een polyrepo nodig als ik microservices gebruik?

Nee. Architectuur (microservices) en repostructuur (mono/poly) zijn onafhankelijke beslissingen. Grote teams houden tientallen microservices in één monorepo; onafhankelijk deployen blijft mogelijk.

Kan ik later van de een naar de ander migreren?

Ja. Met git subtree of git filter-repo kun je repositories samenvoegen of splitsen met behoud van de historie. De migratie is niet gratis, maar wel haalbaar; overlaad de eerste beslissing dus niet.

Laten we samen de juiste structuur voor je project bepalen. We kunnen je bestaande repo's, CI-pijplijn en teamworkflow bekijken en daarna de monorepo- of polyrepo-indeling opzetten die bij je past. Neem contact op en laten we je behoeften bespreken.