Monorepo uitgelegd: voordelen, uitdagingen en best practices

Je werkt aan een project. De frontend staat in de ene repo, de backend in een andere en gedeelde libraries in een derde. En jij wisselt constant van repo en hoopt dat versies niet uit de pas gaan lopen.

Stel je nu voor dat alles op één plek staat. Eén repo voor al je projecten, gedeelde code die meteen wordt bijgewerkt en wijzigingen die in één enkele commit doorstromen. 

Monorepos maken dat mogelijk. Daarom gebruiken veel grote techbedrijven het ook, zoals: 

• Google bouwde Piper met grootschalige automatisering
• Meta schaalt Mercurial op
• Microsoft draait Windows in een Git-monorepo met VFS for Git
• Uber verhuisde zelfs van mono > multi > terug naar mono zodra de tooling bij was

In deze gids leer je wat een monorepo is, hoe die zich verhoudt tot polyrepos, en welke belangrijkste voordelen, uitdagingen en best practices je moet kennen. 

Wat is een monorepo?

Een monorepo (monolithische repository) betekent één repository. In een monorepo staan al je verschillende projecten op dezelfde plek, in plaats van opgesplitst over aparte repositories. 

Hoewel de projecten naast elkaar staan, zijn ze nog steeds onafhankelijk. Je kunt ze dus onafhankelijk bouwen, testen en deployen, maar je profiteert er ook van dat alles bij elkaar op één plek staat.

Maar let op: een monolithische applicatie en een monorepo zijn niet hetzelfde:  

• Een monolithische applicatie (monoliet) is één softwareapplicatie die als één geheel wordt gebouwd en uitgevoerd, meestal met dezelfde dataset. Die kan in een monorepo staan (als één van de vele projecten).
• Monorepo slaat code op en beheert die zo dat veel projecten in dezelfde repo leven, maar nog steeds onafhankelijk van elkaar zijn. 

Een monorepo is geen monolithische app. Sterker nog, monorepos werken vaak heel goed met microservices, omdat elke service in dezelfde repo kan staan en toch onafhankelijk blijft.

Het concept van de monorepo is niet nieuw. 

Begin jaren 2000 begonnen grote techbedrijven een benadering met een "gedeelde codebase" te omarmen. Het idee was simpel: in plaats van code over veel repos te verspreiden, zet je alles op één plek om samenwerking makkelijker te maken.

Sindsdien hebben grote techbedrijven zoals Google, Meta, Microsoft, Airbnb, Twitter (X), Uber en Pinterest monorepos omarmd om hun grote en snel veranderende codebases te beheren.

Monorepo vs. polyrepo

Het tegenovergestelde van een monorepo is een polyrepo (multirepo). Laten we zien hoe dat verschilt.  

Polyrepo

Een polyrepo, ook wel multirepo genoemd, betekent dat elk project een eigen, aparte repository heeft. 

Zo kan de frontendcode in de ene repository staan, de backend in een andere en gedeelde libraries apart. Elke repository wordt onafhankelijk beheerd met eigen dependencies en workflows.

Monorepo vs. polyrepo. Afbeelding door de auteur.

Snel overzicht van de belangrijkste verschillen 

Laten we kijken wat de belangrijkste verschillen zijn tussen monorepos en polyrepos: 

Voordelen van een monorepo

Monorepos bieden veel voordelen. Hier zijn er een paar: 

Betere samenwerking en zichtbaarheid

Als alle code op één plek staat, kan iedereen zien wat er gebeurt. Je kunt andere projecten bekijken, ervan leren of zelfs een handje helpen als dat nodig is. 

Dat maakt teamwork soepeler, helpt teams samenwerken en vermindert silo’s.

Eenvoudiger dependencybeheer 

Als verschillende projecten dezelfde libraries gebruiken maar hun eigen versies aanhouden, kan het snel rommelig worden. 

Zo gebruikt het ene project een oudere versie terwijl een ander een nieuwere gebruikt. Dat kan de code lastiger maakbaar draaien en je besteedt mogelijk veel tijd aan het tweemaal oplossen van hetzelfde probleem.

In een monorepo staat de gedeelde code echter op één plek. Je werkt die één keer bij en elk project krijgt de fix meteen. Je hoeft geen versieverschillen op te sporen of conflicten tussen versies op te lossen.

Atomische commits en makkelijker refactoren 

Soms moet je een wijziging doorvoeren die meer dan één project raakt. Bijvoorbeeld wanneer je een gedeelde library wilt updaten. Met een monorepo kun je die code bijwerken en de fixes voor alle projecten in één commit toepassen. 

Zo blijven alle projecten in sync en hoef je je geen zorgen te maken dat je per ongeluk andere code verstoort. 

Consistente tooling en processen

Met één repo is er één manier om te bouwen, testen en deployen. Je hoeft geen verschillende setups voor verschillende projecten te onthouden. Dat maakt het voor nieuwe teamleden makkelijk om te starten zonder gedoe. 

Snellere iteratie voor bepaalde workflows

Als je twee of meer projecten hebt die van dezelfde code afhangen, bijvoorbeeld een gedeelde library of utility, hoef je niet elk project één voor één in aparte repositories bij te werken. 

Met een monorepo update je de code één keer en alle projecten in die repository krijgen de wijziging direct. In plaats van te wisselen tussen afzonderlijke repositories, kun je aanpassingen op één plek doen en overal tegelijk het effect zien.

Dit helpt in een paar alledaagse situaties: 

• Als je gedeelde code refactort, update je de library en elke service die ervan afhangt krijgt die update meteen. 
• Als je een feature uitrolt die meer dan één app raakt, kun je alles samen releasen in plaats van af te stemmen over verschillende repos. 
• Zelfs je CI/CD-pipelines worden eenvoudiger omdat builds en tests tegen dezelfde codebase draaien in plaats van gedupliceerd te zijn.

Dit alles vermindert heen-en-weer, beperkt contextswitches en verkort feedbackloops. Daardoor ga je sneller itereren zonder extra overhead.

Uitdagingen van een monorepo

Monorepos brengen veel voordelen, maar ook enkele uitdagingen. Dit zijn de belangrijkste:

Schaalbaarheid en performanceproblemen 

Naarmate de repo groter wordt, gaan dagelijkse taken zoals clonen, zoeken of hem zelfs maar openen in je editor trager. Waarom? Omdat Git oorspronkelijk niet is gebouwd voor enorme codebases. Grote bedrijven voelen die druk dus vaak.

Langere build- en testtijden

Omdat alle projecten op dezelfde plek bestaan, kan een kleine wijziging veel extra werk voor je CI/CD-pipeline triggeren. Daardoor zitten developers te wachten tot builds of test-suites klaar zijn voordat ze kunnen mergen of releasen. 

Na verloop van tijd kunnen deze vertragingen extra problemen veroorzaken, zoals het blokkeren van ander werk en het lastiger maken om kleine, frequente wijzigingen door te voeren.

Neem Uber: toen hun Go-monorepo miljoenen regels code bereikte, moesten sommige engineers uren wachten op builds en validatie voordat ze konden mergen. 

Na een tijd wisten ze dit te versnellen met tools als Bazel en aangepaste build-queues. Toch laat het zien hoe snel CI een bottleneck kan worden wanneer al je projecten één repository delen.

Risico op een gebroken main branch 

De main branch is de standaardbranch in Git waar de laatste stabiele versie van je code staat. In een monorepo werkt iedereen vanaf deze gedeelde branch, dus als één wijziging hem breekt, kan het hele team (of bedrijf) geblokkeerd zijn tot het is opgelost.

Neem Airbnb. Zij hanteerden een democratische deployment (elke engineer kon z’n werk testen en in productie zetten zonder op een releasemanager te wachten). 

Dat voelde eerst snel, maar naarmate het bedrijf groeide, werd het beheer lastig omdat al hun code in één grote monorepository stond. Teamleden zetten tegelijkertijd wijzigingen in productie, updates botsten en het werd moeilijk om oorzaken van problemen te vinden.

Toegangsbeheer en beveiliging

Toegang beperken is lastig in een monorepo omdat alle code, configuratiebestanden, build-scripts en andere resources samen worden opgeslagen. Standaard kan elke developer met repo-toegang meestal al deze onderdelen bekijken en wijzigen. 

Dat is prima voor open samenwerking, maar een uitdaging wanneer bepaalde onderdelen, zoals security keys, deploymentscripts of propriëtaire algoritmes, strengere rechten vereisen.

Zo kan een bedrijf de code van zijn website in dezelfde monorepo houden. Developers die aan de website werken, hebben niet per se toegang nodig tot productieserver-credentials, maar omdat alles op één plek staat, is het lastig te voorkomen dat ze die gevoelige bestanden per ongeluk inzien of bewerken.

Leercurve voor nieuwe developers 

Voor nieuwkomers kan een enorme repo met veel projecten overweldigend aanvoelen. Waarom? Omdat er zoveel bestanden en mappen zijn dat het lastig is te weten waar te beginnen of wat relevant is voor hun werk. 

Ze moeten ook de projectstructuur, tools en dependencies leren voordat ze met vertrouwen builds kunnen draaien of wijzigingen kunnen doorvoeren, wat hun voortgang vertraagt tot ze met alles bekend zijn.

Best practices voor monorepo-beheer

Om te zorgen dat een monorepo soepel werkt, zijn dit dingen die je zou moeten doen:

• Houd de repo logisch georganiseerd. Zet gerelateerde projecten bij elkaar, gebruik duidelijke namen en maak het makkelijk om te vinden wat je nodig hebt.
• Vermijd langlevende branches. Probeer trunk-based development, waarbij iedereen vaak wijzigingen in de main branch merge’t. Dat houdt de repo schoon en vermindert conflicten. 
• Pin dependencies op specifieke versies zodat iedereen in sync blijft. Upgrade ze repo-breed tegelijkertijd om mismatches te voorkomen. 
• Gebruik moderne buildtools zoals Bazel, Buck, Nx, Pants, Rush of Lerna om builds te versnellen en de complexiteit van grote repos te beheersen. 
• Bouw of test niet de hele repo opnieuw als slechts een klein deel is gewijzigd. Gebruik differentiële builds en gerichte tests om tijd te besparen en developers sneller feedback te geven. 
• Stel Git CODEOWNERS in op je VCS-platform (bijv. GitHub/GitLab) om gevoelige gebieden zoals deploymentscripts of configuratiebestanden te beschermen, en vereis dat de juiste teams wijzigingen reviewen.

Populaire tools voor monorepo-beheer

Een monorepo kan ingewikkeld worden naarmate projecten groeien. Om het makkelijker te maken, zijn veel tools gebouwd om te helpen met builds, dependencies en om alles georganiseerd te houden.  

Hier zijn een paar van de meest gebruikte:

Bazel 

Bazel is een open-source build-systeem dat bij Google is gemaakt om zeer grote en complexe codebases aan te kunnen. 

Dit zijn enkele kernfeatures:

• Snelle builds: Bouwt alleen opnieuw wat is gewijzigd, met geavanceerde caching, geoptimaliseerde dependency-analyse en parallelle uitvoering.
• Multitalige ondersteuning: Werkt over verschillende platforms en talen, waaronder Java, C++, Go, Android en iOS, en op Windows, macOS en Linux.
• Schaalt eenvoudig: Verwerkt zowel enorme monorepos als meerdere repositories, geschikt voor organisaties van elke omvang.
• Uitbreidbaar: Laat nieuwe talen en platforms toevoegen met een extensiesysteem, ondersteund door een groeiende community.

Bazel wordt vertrouwd door bedrijven als Google, Stripe en Dropbox om bedrijfskritische infrastructuur en applicaties te bouwen en te testen.

Nx

Nx is een open-source toolkit voor het beheren van monorepos en is vooral populair in JavaScript en TypeScript, met sterke ondersteuning voor frameworks zoals React, Angular, Vue en NestJS. Het helpt teams meerdere apps en libraries op één plek te organiseren, terwijl builds en tests snel blijven. 

Dit zijn enkele kernfeatures: 

• Slimme task runner: Begrijpt hoe onderdelen van je code van elkaar afhangen, zodat alleen nodig werk draait en tijdverspilling wordt voorkomen.
• Werkt met wat je al hebt: Draait bestaande scripts, zoals npm- of Gradle-taken, zodat je je setup niet hoeft te veranderen.
• Nx Cloud: Versnelt de ontwikkelcyclus met remote caching, snellere CI-runs en tools die helpen problemen automatisch te detecteren en te verhelpen.
• Extra tools: Features zoals Nx Console bieden autocomplete, een visuele projectgrafiek en makkelijke manieren om taken te beheren.

Lerna

Lerna is een van de eerste en meest vertrouwde tools voor het beheren van JavaScript- en TypeScript-monorepos. Het maakt het eenvoudig om meerdere packages in één repository te organiseren en helpt bij het bouwen, testen en publiceren ervan.

Sterker nog, enkele van de bekendste projecten, zoals Create React App, Jest en NestJS, hebben Lerna gebruikt om hun packages te beheren. 

Enkele kernfeatures zijn: 

• Slimme builds: Voorkomt herhaald werk door gecachte resultaten te hergebruiken in plaats van dezelfde code opnieuw te bouwen.
• Snelle uitvoering: Taken draaien parallel maar respecteren wel de volgorde van dependencies.
• Gedistribueerde caching: Buildresultaten kunnen worden gedeeld tussen developers en CI-systemen, wat buildtijden verkort.
• Package-publicatie: Vereenvoudigt publiceren naar npm met zowel gedeelde als onafhankelijke versionering.
• Schaalbaarheid: Verspreid workloads over meerdere machines zonder extra setup.
• Visualisatie: Wordt geleverd met tools om te laten zien hoe projecten en dependencies in je repo samenhangen.
• Weinig setup: Vereist weinig configuratie, zodat je je bestaande npm-scripts kunt behouden en ze sneller kunt draaien.

Pants

Pants is een snel en gebruiksvriendelijk build-systeem dat goed werkt voor monorepos van verschillende groottes. Het begon met focus op Python maar ondersteunt nu ook Go, Java, Scala, Kotlin, Shell en Docker, met meer talen in aantocht. 

Daarom wordt het veel gebruikt en vertrouwd door bedrijven zoals Coinbase, IBM, Slack, Salesforce en Orca Security, maar ook door veel kleinere teams.

Dit zijn enkele kernfeatures:

• Makkelijk te adopteren: Vereist minimale configuratie en kan de meeste build-informatie automatisch afleiden, dus minder boilerplate om te onderhouden.
• Veilige builds: Ondersteunt meerdere dependency-resolves en lockfiles, waardoor reproduceerbare builds ontstaan die beter bestand zijn tegen supply-chain-aanvallen.
• Flexibel: Werkt op bestandsniveau en kan daardoor complexe of verstrengelde dependency-structuren aan zonder strikte modulariteit af te dwingen.
• Uitbreidbaar: Biedt een plugin-systeem met Python, zodat teams het naar eigen behoefte kunnen aanpassen.
• Git-aware: Detecteert veranderingen tussen branches en draait alleen de tests of builds die geraakt zijn.

Rush 

Rush is een monorepo-tool ontworpen voor JavaScript-projecten die meerdere packages binnen één repository moeten beheren.

Dit zijn enkele kernfeatures: 

• Gemaakt voor schaal: Ondersteunt parallelle, incrementele en gedistribueerde builds zodat zelfs enorme repos efficiënt blijven.

• Teamcoördinatie: Houdt dependency-versies consistent, reviewt nieuwe packages vóór toevoeging en ondersteunt zowel gedeelde als onafhankelijke versionering.
• Betrouwbare installs: Ondersteunt pnpm (aanbevolen), npm en Yarn om installs voorspelbaar te maken.
• Alles-in-één tool: Beheert installs, linking, builds, publiceren, versiebeheer en changelogs op één plek.

Rush is een open-source en vertrouwd platform, gebruikt door grote producten zoals Azure SDK, HBO Max, OneDrive, SharePoint, Office 365 en Wix.

Turborepo

Turborepo is een high-performance build-systeem dat JavaScript- en TypeScript-monorepos sneller en makkelijker te beheren maakt. Het richt zich op het oplossen van veelvoorkomende schaalproblemen wanneer meerdere apps en packages in dezelfde repository samenleven.

Dit zijn enkele kernfeatures:

• Remote caching: Slaat resultaten van builds en tests op zodat hetzelfde werk nooit twee keer hoeft te draaien, wat CI-tijden verkort.
• Taakscheduling: Voert taken in de juiste volgorde en parallel uit over alle beschikbare cores voor maximale snelheid.
• Stapsgewijze adoptie: Kan in minuten aan elke repo worden toegevoegd, gebruikt bestaande package.json-scripts en werkt met npm, Yarn of PNPM.
• Lightweight clonen: Laat developers alleen de delen van een monorepo clonen die ze nodig hebben, wat de setuptijd verkort.
• Geoptimaliseerde workflows: Bouwt alleen wat is veranderd, waardoor feedbackloops snel blijven.
• Vertrouwde developer-ervaring: Werkt met standaard Git-workflows en vereist geen veranderingen in hoe teams al code beheren.

Moon

Moon is een snelle monorepo-beheertool, geschreven in Rust. Het ondersteunt talen zoals JavaScript, TypeScript, Rust, Go en Ruby.

Dit zijn enkele kernfeatures:

• Snelheid: Gebruikt slimme caching en incrementele builds zodat alleen gewijzigde code opnieuw wordt gebouwd.
• Samenwerking: Remote caching deelt resultaten tussen teamgenoten en CI.
• Cross-platform: Draait op Linux, macOS en Windows.
• Projectgrafiek: Brengt dependencies in kaart om grote repos te organiseren en op te schalen.

Lage

Lage is een task runner voor monorepos die focust op snelheid en efficiëntie. Het helpt teams voorkomen dat werk opnieuw wordt opgebouwd dat al gedaan is.

Enkele kernfeatures zijn:

• Slaat herhaald werk over: Hergebruikt resultaten lokaal of van teamgenoten, zodat builds niet dubbel draaien.
• Snelle setup: Makkelijk te configureren en werkt in verschillende omgevingen.
• Caching: Ondersteunt lokale cache of externe opslag om CI-pipelines te versnellen.
• Inzichten: Inclusief tools om builds te profileren en dependency-grafieken te visualiseren.

Yarn workspaces

Yarn introduceerde workspaces om het beheer te vereenvoudigen van projecten met veel packages binnen één repo (een monorepo). 

Dit zijn enkele kernfeatures:

• Geen dubbele installs: Gemeenschappelijke dependencies worden slechts één keer aan de root geïnstalleerd, zodat je opgeblazen node_modules in elke package voorkomt.
• Automatisch linken: Als de ene package afhankelijk is van een andere in dezelfde repo, linkt Yarn die voor je.
• Eén lockfile: Heeft één yarn.lock voor de hele repo, wat versies consistent houdt over alle packages.

Wanneer gebruik je een monorepo

Laten we een paar veelvoorkomende scenario’s bekijken waarin een monorepo handig voor je is: 

Kleine tot middelgrote teams met gedeelde code

Als je team klein is en veel code over projecten heen wordt hergebruikt, kan een monorepo je tijd besparen. Omdat iedereen in hetzelfde gebied kan werken en gedeelde libraries zonder extra moeite in sync blijven. Dat is dus een win-win.  

Projecten met nauwe dependency-relaties

Wanneer verschillende projecten nauw van elkaar afhankelijk zijn, houd ze dan in één repo. Zo kunnen wijzigingen samen in één commit plaatsvinden in plaats van te jongleren met meerdere repos.

Organisaties die uniforme tooling en zichtbaarheid zoeken

Met een monorepo kun je een uniforme CI/CD-configuratie opzetten. Dat betekent niet dat er maar één pipeline is voor alle projecten, maar wel dat je pipelines kunt optimaliseren zodat ze alleen de builds en tests draaien die door recente codewijzigingen geraakt zijn, wat tijd en resources bespaart.

Maar monorepos zijn niet in alle gevallen ideaal. Als je projecten volledig onafhankelijk zijn, of als je strikte toegangscontrole nodig hebt (waarbij sommige teams specifieke code niet mogen zien), dan zijn polyrepos (meerdere repos) waarschijnlijk geschikter.

De voor- en nadelen afwegen

Hier is een snel overzicht van de voor- en nadelen van monorepos:

Tot slot

Een monorepo kan samenwerking makkelijker maken, dependencies eenvoudiger en iteratie sneller, maar brengt ook echte uitdagingen mee rond schaal, performance en toegang. De beslissing om er één te adopteren zou een strategische keuze moeten zijn op basis van hoe je teams zijn ingericht, hoe nauw je projecten van elkaar afhangen en of je bereid bent in de juiste tooling te investeren.

Maar zonder sterke samenwerkingsgewoontes en duidelijke eigenaarschap zal zelfs de beste monorepo-setup worstelen. Als je dit pad verkent, is het de moeite waard eerst je basis op orde te brengen. De Software Engineering Principles in Python-cursus is een goede plek om te beginnen. Die helpt je de praktijken opbouwen die een monorepo laten slagen.