Wat is een monorepo en wanneer gebruik je er een?

Als je meerdere applicaties bouwt die met elkaar samenhangen, bijvoorbeeld een frontend, een backend-API en een gedeelde componentenbibliotheek, ontstaat al snel de vraag: zet je dat in aparte repositories of in één geheel? Die keuze bepaalt hoe soepel je team later kan samenwerken en releasen.

Waarom teams voor een monorepo kiezen

Het grootste voordeel van een monorepo is dat gedeelde code, zoals een designsysteem, een set TypeScript-types of een authenticatielaag, in één keer wordt aangepast en direct beschikbaar is voor alle projecten die deze gebruiken. Bij aparte repositories moet je een package publiceren, versienummers ophogen en die update handmatig doortrekken naar elk project. Dat kost tijd en leidt vaak tot projecten die op verschillende, verouderde versies van dezelfde gedeelde code blijven hangen.

Een monorepo maakt ook refactoren over projectgrenzen heen makkelijker. Verander je een functiesignatuur die door drie applicaties wordt gebruikt, dan zie je in één pull request meteen alle plekken die moeten meebewegen, in plaats van dat je losse pull requests moet coördineren in drie aparte repositories.

Wat een monorepo in de praktijk bevat

Een typische monorepo-structuur bestaat uit een map apps/ met de daadwerkelijke applicaties (bijvoorbeeld een webapp en een admin-dashboard) en een map packages/ met gedeelde bouwstenen (bijvoorbeeld een UI-component-bibliotheek, een API-client of gedeelde configuratie). Elk onderdeel heeft zijn eigen package.json, maar ze delen dezelfde git-geschiedenis, dezelfde issue-tracker en vaak dezelfde CI-pipeline.

Voor een team dat bijvoorbeeld werkt aan een SaaS-applicatie met een aparte marketingwebsite, kan het slim zijn om de gedeelde componenten (huisstijl, formulieren) in één packages-map te zetten, terwijl de applicatie en de website als aparte apps in dezelfde monorepo blijven.

Toolkeuze: Turborepo, Nx en workspaces

Naarmate een monorepo groeit, wordt de bouwtijd een probleem: waarom het hele project opnieuw builden als je maar één bestand hebt aangepast? Tools zoals Turborepo en Nx lossen dit op door alleen de gewijzigde projecten en hun afhankelijkheden opnieuw te bouwen, en door buildresultaten te cachen zodat een herhaalde build in seconden klaar is in plaats van minuten.

Voor package-beheer gebruik je workspaces: een functie van npm, pnpm of Yarn waarmee je binnen één repository meerdere package.json-bestanden kunt beheren en onderling naar elkaar kunt verwijzen zonder ze eerst te publiceren naar een package-registry. Voor een klein team met twee of drie projecten is dit vaak al voldoende, zonder dat je Turborepo of Nx nodig hebt.

Monorepo versus polyrepo: de afweging

Het alternatief, een polyrepo, geeft elk project zijn eigen repository met eigen versiebeheer, eigen toegangsrechten en een eigen CI/CD-pipeline. Dat is prettig als teams volledig onafhankelijk van elkaar willen werken en releasen, of als externe partijen alleen toegang mogen krijgen tot één specifiek onderdeel.

De praktische vuistregel: kies een monorepo als projecten sterk van elkaar afhankelijk zijn en door hetzelfde team worden onderhouden. Kies een polyrepo als projecten losstaand zijn, door verschillende teams worden beheerd, of een eigen releasecyclus nodig hebben. Voor de meeste MKB-projecten met één ontwikkelteam is een monorepo eenvoudiger te onderhouden dan een verzameling losse repositories die synchroon gehouden moeten worden.

Onze tip: begin klein. Zet niet meteen alles in een complexe monorepo-setup met Turborepo en Nx als je nog maar twee projecten hebt. Start met een eenvoudige map-structuur en npm- of pnpm-workspaces, en voeg pas zwaardere tooling toe zodra de buildtijden daadwerkelijk een probleem worden.