Monorepo spiegato: vantaggi, sfide e best practice

Stai lavorando a un progetto. Il frontend è in un repo, il backend in un altro e le librerie condivise in un terzo. E continui a cambiare repo, sperando che le versioni non vadano fuori sincronia.

Ora immagina tutto in un unico posto. Un unico repo per tutti i tuoi progetti, codice condiviso che si aggiorna all'istante e modifiche che si propagano con un solo commit. 

I monorepo permettono tutto questo. Ecco perché molte big tech lo usano, ad esempio: 

• Google ha creato Piper con automazione su larga scala
• Meta ha scalato Mercurial
• Microsoft esegue Windows in un monorepo Git con VFS for Git
• Uber è persino passata da mono > multi > di nuovo a mono quando gli strumenti sono maturati

In questa guida scoprirai cos'è un monorepo, come si confronta con i polyrepo e i principali vantaggi, sfide e best practice da conoscere. 

Cos'è un Monorepo?

Un monorepo (repository monolitico) significa un unico repository. In un monorepo, tutti i tuoi diversi progetti risiedono nello stesso posto, invece di essere suddivisi in repository separati. 

Anche se i progetti sono affiancati, restano comunque indipendenti. Questo significa che puoi buildare, testare e distribuire in modo autonomo, con il vantaggio di tenere tutto insieme in un unico punto.

Attenzione però: un'applicazione monolitica e un monorepo non sono la stessa cosa:  

• Un'applicazione monolitica (monolite) è un'unica applicazione software costruita ed eseguita come un solo blocco, di solito lavorando sullo stesso dataset. Può stare dentro un monorepo (come uno dei tanti progetti).
• Monorepo archivia e gestisce il codice in modo che molti progetti vivano nello stesso repo, restando però indipendenti tra loro. 

Un monorepo non è un'app monolitica. Anzi, i monorepo spesso funzionano molto bene con le microservizi, perché ogni servizio può vivere nello stesso repo pur restando indipendente.

Il concetto di monorepo non è nuovo. 

All'inizio degli anni 2000, le principali aziende tech hanno iniziato ad adottare un approccio di "codebase condivisa". L'idea era semplice: invece di sparpagliare il codice in molti repo, mettere tutto in un posto per facilitare la collaborazione.

Da allora, big tech come Google, Meta, Microsoft, Airbnb, Twitter (X), Uber e Pinterest hanno adottato monorepo per gestire codebase ampie e in rapida evoluzione.

Monorepo vs. Polyrepo

L'opposto di un monorepo è un polyrepo (multirepo). Vediamo in cosa differiscono.  

Polyrepo

Un polyrepo, detto anche multirepo, è quando ogni progetto ha il proprio repository separato. 

Per esempio, il codice del frontend potrebbe stare in un repository, il backend in un altro e le librerie condivise a parte. Ogni repository è gestito in modo indipendente con le sue dipendenze e i suoi workflow.

Monorepo vs. polyrepo. Immagine dell'autore.

Uno sguardo rapido alle differenze chiave 

Vediamo quali sono le principali differenze tra monorepo e polyrepo: 

Vantaggi di un Monorepo

I monorepo offrono molti vantaggi. Eccone alcuni: 

Collaborazione e visibilità migliorate

Quando tutto il codice è in un unico posto, tutti possono vedere cosa sta succedendo. Puoi dare un'occhiata ad altri progetti, imparare da loro o anche dare una mano se serve. 

Questo rende il lavoro di squadra più fluido, aiuta i team a collaborare e riduce i silos.

Gestione delle dipendenze semplificata 

Se progetti diversi usano le stesse librerie ma mantengono le proprie versioni, la situazione si complica in fretta. 

Per esempio, un progetto usa una versione più vecchia mentre un altro una più nuova. Questo può rendere il codice più difficile da eseguire e potresti finire per risolvere lo stesso problema in più posti.

In un monorepo, invece, il codice condiviso risiede in un'unica posizione. Lo aggiorni una volta e ogni progetto riceve subito la correzione. Non devi rincorrere incongruenze di versione o gestire conflitti tra versioni diverse.

Commit atomici e refactoring più semplice 

A volte devi fare una modifica che impatta più di un progetto. Per esempio, potresti voler aggiornare una libreria condivisa. Con un monorepo, puoi aggiornare quel codice e applicare le correzioni a tutti i progetti con un solo commit. 

Questo mantiene tutti i progetti sincronizzati, così non rischi di interrompere altro codice per sbaglio. 

Strumenti e processi coerenti

Con un solo repo, c'è un solo modo di buildare, testare e distribuire. Non devi ricordare setup diversi per progetti diversi. Questo aiuta anche i nuovi membri del team a partire senza confusione. 

Iterazione più rapida per certi workflow

Se hai due o più progetti che dipendono dallo stesso codice, per esempio una libreria o una utility condivisa, non devi aggiornare ogni progetto uno per uno in repository separati. 

Con un monorepo, aggiorni il codice una volta sola e tutti i progetti dentro quel repository ricevono subito la modifica. Questo significa che, invece di passare da un repository all'altro, puoi intervenire in un unico posto e vedere l'impatto ovunque, subito.

Questo aiuta in alcune situazioni quotidiane: 

• Quando fai refactoring del codice condiviso, aggiorni la libreria e ogni servizio che la usa riceve subito l'aggiornamento. 
• Quando rilasci una feature che tocca più di un'app, puoi pubblicare tutto insieme invece di coordinare tra repo diversi. 
• Anche le pipeline CI/CD diventano più semplici perché build e test girano sulla stessa codebase invece di essere duplicati.

Tutto questo riduce i rimbalzi, limita il context switching e accorcia i cicli di feedback. Di conseguenza, velocizza l'iterazione senza overhead extra.

Sfide di un Monorepo

I monorepo portano molti vantaggi, ma anche alcune sfide. Ecco le principali:

Problemi di scalabilità e performance 

Man mano che il repo cresce, attività quotidiane come clonare, cercare o anche solo aprirlo nell'editor iniziano a rallentare. Perché? Perché Git non è stato originariamente pensato per codebase enormi. Quindi le grandi aziende spesso sentono il peso.

Tempi di build e test più lunghi

Poiché tutti i progetti esistono nello stesso posto, una piccola modifica può innescare molto lavoro extra per la tua pipeline CI/CD. Per questo gli sviluppatori finiscono per aspettare a lungo che build o suite di test finiscano prima di poter fare merge o rilasciare il codice. 

Col tempo, questi ritardi possono generare ulteriori problemi, come bloccare altro lavoro e rendere più difficile implementare modifiche piccole e frequenti.

Prendi Uber, per esempio: quando il loro monorepo Go ha raggiunto milioni di righe di codice, alcuni ingegneri aspettavano ore che build e validazioni finissero prima di poter fare merge. 

Con il tempo hanno velocizzato le cose con strumenti come Bazel e code di build personalizzate. Tuttavia, questo evidenzia quanto rapidamente la CI possa diventare un collo di bottiglia quando tutti i progetti condividono un unico repository.

Rischi di rottura del branch main 

Il branch main è il branch predefinito in Git dove esiste la versione stabile più recente del tuo codice. In un monorepo, tutti lavorano da questo branch condiviso, quindi se una modifica lo rompe, l'intero team (o l'azienda) può rimanere bloccato finché non si risolve.

Prendi Airbnb come esempio. Gestivano un deployment democratico (qualsiasi ingegnere poteva testare il proprio lavoro e metterlo in produzione senza aspettare un release manager). 

All'inizio sembrava veloce, ma con la crescita dell'azienda gestire tutto è diventato difficile perché tutto il loro codice era in un unico, grande monorepository. I membri del team mettevano in produzione modifiche contemporaneamente e gli aggiornamenti andavano in conflitto, rendendo difficile trovare la causa dei problemi.

Controllo degli accessi e sicurezza

È difficile limitare gli accessi in un monorepo perché tutto il codice, i file di configurazione, gli script di build e altre risorse sono archiviati insieme. Per impostazione predefinita, chi ha accesso al repository può di solito visualizzare e modificare tutti questi componenti. 

Va bene per una collaborazione aperta, ma è una sfida quando alcune parti, come chiavi di sicurezza, script di deployment o algoritmi proprietari, richiedono permessi più rigidi.

Per esempio, un'azienda potrebbe tenere il codice del sito web nello stesso monorepo. Gli sviluppatori che lavorano sul sito non hanno necessariamente bisogno delle credenziali dei server di produzione, ma poiché tutto vive in un unico posto, può essere difficile impedire che vedano o modifichino accidentalmente quei file sensibili.

Curva di apprendimento per i nuovi sviluppatori 

Per chi è nuovo, un repo vasto con molti progetti può risultare travolgente. Perché? Perché ci sono così tanti file e cartelle che è difficile capire da dove iniziare o cosa è rilevante per il proprio lavoro. 

Devono anche imparare struttura, strumenti e dipendenze del progetto prima di poter eseguire build o fare modifiche con sicurezza, il che può rallentarli finché non prendono confidenza.

Best practice per la gestione di un Monorepo

Per far funzionare al meglio un monorepo, ecco alcune cose da fare:

• Tieni il repo organizzato in modo sensato. Raggruppa i progetti correlati, usa nomi chiari e rendi facile a chiunque trovare ciò che serve.
• Evita branch di lunga durata. Prova il trunk-based development, in cui tutti fanno merge spesso nel branch main. Questo mantiene il repo pulito e riduce i conflitti. 
• Fissa le dipendenze a versioni specifiche così tutti restano in sincronia. Aggiornale in tutto il repo contemporaneamente per evitare discrepanze. 
• Usa strumenti di build moderni come Bazel, Buck, Nx, Pants, Rush o Lerna per velocizzare i build e gestire la complessità dei repo grandi. 
• Non ricostruire o ritestare l'intero repo se è cambiata solo una piccola parte. Usa build differenziali e test mirati per risparmiare tempo e dare feedback più rapido agli sviluppatori. 
• Configura i Git CODEOWNERS nella tua piattaforma VCS (ad es. GitHub/GitLab) per proteggere aree sensibili come script di deployment o file di configurazione e richiedere la revisione dei team giusti.

Strumenti popolari per la gestione dei Monorepo

Un monorepo può diventare complicato man mano che i progetti crescono. Per semplificare, sono stati creati molti strumenti per aiutare con build, dipendenze e per tenere tutto organizzato.  

Ecco i più comuni:

Bazel 

Bazel è un sistema di build open source creato da Google per gestire codebase molto grandi e complesse. 

Ecco alcune caratteristiche principali:

• Build veloci: Ricostruisce solo ciò che è cambiato, usando caching avanzato, analisi ottimizzata delle dipendenze ed esecuzione in parallelo.
• Supporto multi-linguaggio: Funziona su piattaforme e linguaggi diversi, tra cui Java, C++, Go, Android e iOS, e su Windows, macOS e Linux.
• Scala facilmente: Gestisce sia monorepo enormi sia più repository, adatto a organizzazioni di qualsiasi dimensione.
• Estensibile: Consente di aggiungere nuovi linguaggi e piattaforme con il suo sistema di estensioni, supportato da una community in crescita.

Bazel è adottato da aziende come Google, Stripe e Dropbox per buildare e testare infrastrutture e applicazioni mission-critical.

Nx

Nx è un toolkit open source per gestire monorepo ed è particolarmente popolare in JavaScript e TypeScript, con un forte supporto per framework come React, Angular, Vue e NestJS. Aiuta i team a organizzare più app e librerie in un unico posto, mantenendo build e test veloci. 

Ecco alcune caratteristiche principali: 

• Task runner intelligente: Capisce come le parti del tuo codice dipendono tra loro, quindi esegue solo ciò che serve evitando sprechi di tempo.
• Funziona con ciò che hai già: Esegue script esistenti, come task npm o Gradle, così non devi cambiare il tuo setup.
• Nx Cloud: Accelera il ciclo di sviluppo con caching remoto, CI più rapidi e strumenti che aiutano a rilevare e correggere i problemi automaticamente.
• Strumenti extra: Funzionalità come Nx Console offrono autocomplete, un grafo visivo dei progetti e modi semplici per gestire i task.

Lerna

Lerna è uno dei primi e più affidabili strumenti per gestire monorepo JavaScript e TypeScript. Rende facile organizzare più pacchetti in un unico repository e aiuta a buildare, testare e pubblicarli.

Alcuni dei progetti più noti, come Create React App, Jest e NestJS, hanno usato Lerna per gestire i loro pacchetti. 

Alcune caratteristiche principali: 

• Build intelligenti: Evita di ripetere il lavoro riutilizzando risultati in cache invece di ricostruire lo stesso codice.
• Esecuzione veloce: I task girano in parallelo rispettando l'ordine delle dipendenze.
• Caching distribuito: I risultati dei build possono essere condivisi tra sviluppatori e sistemi CI, riducendo i tempi.
• Pubblicazione dei pacchetti: Semplifica la pubblicazione su npm con versioning sia condiviso sia indipendente.
• Scalabilità: Distribuisce i carichi di lavoro su più macchine senza setup extra.
• Visualizzazione: Strumenti integrati mostrano come progetti e dipendenze si collegano nel tuo repo.
• Setup leggero: Richiede poca configurazione, così puoi mantenere gli script npm esistenti ed eseguirli più velocemente.

Pants

Pants è un sistema di build veloce e facile da usare che funziona bene per monorepo di varie dimensioni. Nato con focus su Python, ora supporta anche Go, Java, Scala, Kotlin, Shell e Docker, con altri linguaggi in arrivo. 

Per questo è ampiamente usato e considerato affidabile da aziende come Coinbase, IBM, Slack, Salesforce e Orca Security, oltre a molti team più piccoli.

Ecco alcune caratteristiche principali:

• Facile da adottare: Richiede configurazione minima e può inferire automaticamente la maggior parte delle info di build, con meno boilerplate da mantenere.
• Build sicure: Supporta più risolutori di dipendenze e lockfile, creando build riproducibili più resistenti ad attacchi alla supply chain.
• Flessibile: Lavora a livello di file, quindi gestisce strutture di dipendenze complesse o intrecciate senza imporre modularità rigida.
• Estensibile: Offre un sistema di plugin in Python per personalizzarlo in base alle proprie esigenze.
• Consapevole di Git: Rileva i cambiamenti tra branch ed esegue solo test o build interessati.

Rush 

Rush è uno strumento per monorepo pensato per progetti JavaScript che richiedono la gestione di più pacchetti all'interno di un unico repository.

Ecco alcune caratteristiche principali: 

• Progettato per scalare: Supporta build paralleli, incrementali e distribuiti, così anche i repo enormi restano efficienti.

• Coordinamento del team: Mantiene coerenti le versioni delle dipendenze, revisiona nuovi pacchetti prima di aggiungerli e supporta versioning sia condiviso sia indipendente.
• Installazioni affidabili: Supporta pnpm (consigliato), npm e Yarn per rendere le installazioni prevedibili.
• Strumento tutto-in-uno: Gestisce installazioni, linking, build, pubblicazione, gestione versioni e changelog in un unico posto.

Rush è una piattaforma open source affidabile, usata da prodotti di primo piano come Azure SDK, HBO Max, OneDrive, SharePoint, Office 365 e Wix.

Turborepo

Turborepo è un sistema di build ad alte prestazioni che rende i monorepo JavaScript e TypeScript più veloci e facili da gestire. Si concentra nel risolvere i tipici problemi di scalabilità che emergono quando più app e pacchetti coesistono nello stesso repository.

Ecco alcune caratteristiche principali:

• Caching remoto: Salva i risultati di build e test così lo stesso lavoro non deve girare due volte, riducendo i tempi in CI.
• Scheduling dei task: Esegue i task nell'ordine corretto e in parallelo su tutti i core disponibili per la massima velocità.
• Adozione incrementale: Può essere aggiunto a qualsiasi repo in pochi minuti, usando gli script package.json esistenti e funzionando con npm, Yarn o PNPM.
• Clonazione leggera: Consente agli sviluppatori di clonare solo le parti del monorepo di cui hanno bisogno, riducendo i tempi di setup.
• Workflow ottimizzati: Builda solo ciò che è cambiato, mantenendo cicli di feedback rapidi.
• Esperienza sviluppatore familiare: Funziona con workflow Git standard e non richiede di cambiare il modo in cui i team gestiscono già il codice.

Moon

Moon è un tool veloce per la gestione dei monorepo, scritto in Rust. Supporta linguaggi come JavaScript, TypeScript, Rust, Go e Ruby.

Ecco alcune caratteristiche principali:

• Velocità: Usa caching intelligente e build incrementali così si ricostruisce solo il codice cambiato.
• Collaborazione: Il caching remoto condivide i risultati tra compagni di squadra e CI.
• Multipiattaforma: Funziona su Linux, macOS e Windows.
• Grafo dei progetti: Mappa le dipendenze per aiutare a organizzare e scalare repo grandi.

Lage

Lage è un task runner pensato per i monorepo che punta su velocità ed efficienza. Aiuta i team a evitare di ricostruire lavoro già fatto.

Alcune caratteristiche principali:

• Salta il lavoro ripetuto: Riutilizza i risultati localmente o da colleghi, così i build non girano due volte.
• Setup rapido: Facile da configurare e funziona su diversi ambienti.
• Caching: Supporta cache locale o storage esterno per velocizzare le pipeline CI.
• Insights: Include strumenti per profilare i build e visualizzare i grafi delle dipendenze.

Yarn workspaces

Yarn ha introdotto i workspaces per semplificare la gestione di progetti con molti pacchetti dentro un unico repo (un monorepo). 

Ecco alcune caratteristiche principali:

• Niente installazioni duplicate: Le dipendenze comuni sono installate una sola volta alla root, evitando node_modules gonfi in ogni pacchetto.
• Linking automatico: Se un pacchetto dipende da un altro nello stesso repo, Yarn li collega automaticamente.
• Un solo lockfile: Un unico yarn.lock per tutto il repo, che mantiene coerenti le versioni tra i pacchetti.

Quando usare un Monorepo

Vediamo alcuni scenari comuni in cui un monorepo può esserti utile: 

Team piccoli o medi con codice condiviso

Se il tuo team è piccolo e molto codice è riutilizzato tra progetti, un monorepo può farti risparmiare tempo. Perché tutti possono lavorare nello stesso posto e le librerie condivise restano allineate senza sforzi extra. Una doppia vittoria.  

Progetti con dipendenze molto strette

Quando i tuoi progetti dipendono strettamente l'uno dall'altro, tienili in un unico repo. Così le modifiche possono avvenire insieme con un solo commit invece di destreggiarti tra più repo.

Organizzazioni che cercano strumenti e visibilità unificati

Con un monorepo puoi configurare una CI/CD unificata. Non significa avere una sola pipeline per tutti i progetti, ma ottimizzare le pipeline affinché eseguano solo i build e i test impattati dai cambiamenti recenti, risparmiando tempo e risorse.

Ma i monorepo non sono perfetti per ogni caso. Se i tuoi progetti sono totalmente indipendenti o se ti servono controlli di accesso rigidi (in cui alcuni team non devono vedere codice specifico), allora i polyrepo (più repo) potrebbero essere la scelta migliore.

Pro e contro a confronto

Ecco una panoramica rapida dei vantaggi e svantaggi dei monorepo:

Considerazioni finali

Un monorepo può rendere la collaborazione più semplice, le dipendenze più gestibili e l'iterazione più veloce, ma comporta anche sfide reali su scala, performance e accessi. Decidere di adottarlo dovrebbe essere una scelta strategica basata su come sono strutturati i tuoi team, quanto strettamente i tuoi progetti dipendono l'uno dall'altro e se sei pronto a investire negli strumenti giusti.

Ma senza solide abitudini di collaborazione e ownership chiara, anche il miglior setup di monorepo farà fatica. Se stai esplorando questa strada, vale la pena affinare prima le basi. Il corso Software Engineering Principles in Python è un ottimo punto di partenza. Ti aiuterà a costruire le pratiche che rendono un monorepo di successo.