The Monorepo Multiplier: 10x Your Team with Better Architecture

So just to give you an idea, I'm giving a talk after 18 months. I decided to take a break, focus more on my health and family. Good news, I am 15 kg lighter, so everything worked out. So I'm here to talk about monorepos.

So just a question. Quick question. How many of you are using monorepos? Okay, a lot of hands. Good. And how many wants to use monorepos? Okay, only one. Okay. Hope I am able to change the perception because monorepos have a very bad name when it comes to the large code bases, right? But still Google does it. And I will not talk about it.

So let's talk about why I prefer monorepos, right? So my journey in monorepos started six years ago. So it was a customer who asked me, says, hey, you know, we have one app and it's a very successful app. I think we can actually replicate this business for many other customers and we make more money. And I was like, okay, so what do you need? So they said like, you know, we have a design system. If we can actually replicate this, it will become easier for us to build new apps and we can go to a new customer and ship them faster. Like we have a new app ready for a new customer within a week. I was like, okay, let's do that. And that's when I decided, sorry, sorry, see 18 months. So that's when I decided like, okay, let's explore monorepos. And I found a tooling which worked for me. And then I thought like, okay, that was the easiest part.

Two years later, I was, not two years, but yeah, four years, close to two years later, I was hired by a company called Silones. They had like a very big code base, but scattered across. So this is what they were doing. I'm just saying four apps, but they had like 30 apps, 30 apps, 30 repositories, 30 different teams doing the same stuff. My job was to work with everyone, clone each repo, install node modules, see the breaking changes, and update all the apps. Upgrading the design system required coordination across all apps, causing slow shipping and team struggles.

When I joined, it took us a month to release a small update due to challenges with Angular upgrades and custom micro frontend solutions. The complexity led to difficulty in identifying breaking changes and rollbacks. The existing system relied on polyrepos, involving building, testing, publishing, and updating multiple apps, leading to dependency management challenges. With teams at different readiness levels for upgrades, creating new versions of the design system often resulted in dependency issues, trapping teams in dependency hell.

They were like, okay, even the rollback was a problem because how should I know which one is breaking? Because you know what we were doing? We used to actually load 30 different apps inside a micro frontend. And it was our own custom solution. So it was all a mess out there.

So like, okay, let's see what we can do. So this was our old system, right? How many of you know about polyrepos? I think everyone, right? I don't have to ask this question. Everyone is using it. I mean, we have been using it for ages, right? Polyrepos. So what we do, we actually work like this.

So you have a changing design system, you build, test, publish, then update the version to app one, app two, app three, app four. And then the cycle continues. You PR, review, merge, and then move on. If you are lucky, there are multiple teams doing it. If you are unlucky, you are the one responsible for everything. Then the other cost is for 30 apps, sometime it happens that 10 teams are ready to upgrade. 10 teams are not ready to upgrade. Then what do you do?

And say, okay, we will support you, 10 guys. 10 guys, you can move on. And then this is how you go into dependency hell. And there is no going back from there. So big misconception when it comes to monorepos, or talking about project is, most people think one repository is one project. Because this is how I think everything started, right? In older days, we had java.net. And everything was one repository, one project. And then microservices came in, people started breaking their apps, and then realized, why should we have microfrontend or micro services? And then it was a bad practice again. So in reality, what can happen is one project can span across multiple repositories, that's polyrepo. And one repository can contain multiple projects, that's monorepo. So let's see. Simple diagram to show you monorepo, polyrepo, and monolith. I'm sure, looking at all of you, I'm sure most of you might have used monoliths. I think that's where we started, right? .NET, Java, single monolith, we deploy everything together. So let's see how the monorepos look like.

So in monorepo, what you do is you have multiple apps. You can share the code. For example, design system in this case. And everyone has the same version. So it's not like multiple versions, no dependency hell, no multiple version management. You can just have the same code base across all environments, easy to fix, easy to move ahead. In polyrepo, you will have your repositories or projects, or part of the projects, scattered across multiple repositories. This is where the dependency hell comes in the picture. When should you use monorepo? I will say always. I mean, that is what I think. And after working for so many years in monorepo space, I think you should always go ahead and recommend monorepo to anyone. But I will give you some pointers of what is the best use case, right, when you should be using monorepos. First one is, of course, when you have multiple projects sharing code dependencies. And I'm sure in today's world, it is very common to do this. A lot of projects actually interdepend on each other within the organization.

A lot of projects actually interdepend on each other within the organization. So a common example is your design system. I don't know when this trend started, but at some point of time, every company wanted their own design system. They're like, no, I'm not going to use maybe ShadC and UI, or maybe Material UI. We will build our own because we are unique. I don't know who is unique. And then shared libraries, right? You have some code which is actually shared across multiple projects, and you say, oh, where should I put this code? So okay, let's create a shared library. And we put it there. Need for atomic changes. I think this is one of the things which at Selonis, we were struggling a lot. We used to make change in one small library, update it at 30 places, and now two apps broke. So our commits actually have scattered across now 32 different libraries, or 32 different code bases. So with actually monorepos, you don't see this. You have actually a breaking change, single commit, right? Because what you're changing, and you actually update the entire monorepo with the same change. For example, a simple API change, right? You added a new parameter. Just think about going to 30 code bases just to update a parameter, and being in a monorepo where you know, oh, if I do something, my build will break anyways. And API updates as well. So these are multiple cases where you get the advantage of atomic changes.

So I still have 10 minutes, so I'll go a little bit faster. And large scale refactoring. A simple example can be upgrading your React version, right? So if you have multiple projects with multiple or different React version, and there is a breaking change, it becomes pain to actually upgrade them. Believe me, people actually leave the companies by the time they finish all the migrations. But in monorepos, you can actually do it in a single upgrade, right? And then, strong code reuse culture. We stopped reinventing the wheel, because everyone is using the same code base, so everyone knows what's happening. And interconnected products, for example, micro frontend and shared backends. This is also one use case where you can actually just go ahead and use monorepos. Why team loves monorepo? I mean, at Selonis, we started from scratch. So we started, like, onboarding, talking to teams, and then started onboarding all of them. Initially, they were resistant, as anyone would be. But once they saw, like, we are now sharing more code, and we have more reusable code, they said, like, okay, that's absolutely fine.

This is what we love. Atomic commits. They started loving it that now they can trace the changes or breaking changes to a single commit. They don't have to actually go across 30 different repositories to do this.

Simplified dependencies. Now, I don't have to actually clone 30 different repositories to figure out which libraries to update or which packages to update. I can just do it in a monorepo. A lot of tooling supports single package JSON file. So you don't have to even maintain multiple package.json files as well. Just depends on the tooling you are using.

Unified CI-CD. So this is one thing which was really amazing, because, you know, 30 different CI-CD pipelines against the one CI-CD pipeline, I'm sure people will just recommend only one, right? And better collaboration. We started working as a team. So at some point of time, we had, like, 400 contributors to the monorepo, and everyone was living happily ever after.

So this is one example from our code base once we moved to monorepo. So we had a legacy code base. I'm sure legacy code bases exist everywhere. And this legacy code base was a dumping ground for all the teams. You need a new function. Where should it go? So this reusable function. So this reusable library. And at some point of time, this reusable library, what was 800 KB, multiplied by 30 projects. So 800 KB into 30. That's like how much code we were shipping. As soon as we moved to monorepo, we removed 98% of the code. Gone. 4 KB of the code left. That's how strong the monorepo reusability culture is.

So when I talk about atomic changes, what I mean about atomic changes. So this is how it looks like. So, for example, if you have multiple projects, what you will do is you will go ahead and upgrade the same code across multiple repositories. Multiple commits will fly across your organization. But in atomic commits, you have a single commit identifying what changed, why you changed it. And you need to trace it back when something goes wrong. So this is a simple example. Right? So, for example, I just upgraded a single parameter. The example I already gave it to you. With monorepo, you can actually catch this early, rather than actually publishing and then figuring out that something is broken for this app, because we missed a parameter. Which is a very normal case. Normal, very easy use case.

Simplified dependencies. Now you have all the projects using the same React version. You don't have the dependency version held, which is generally we have, in case we are using multiple versions of React or multiple versions of Angular or whatever. Unified CICD? Our CICD started looking like a job which is done by experts rather than a mess.

So earlier we had 30 different CICD pipelines, each one pushing their codebase into a database, then pull it back, show it in Microfrontend, and now we just moved into a single CICD pipeline where we know what projects to build, what projects will run Linter, what projects will run the end-to-end test cases, what projects will run unit test cases. We are able to figure out what projects to run, even in that case. For example, let's say a shared library. If I change the shared library and the new function is not being used by my 29 projects, I still need to build those 30 projects every time. In this case, we were just building one. Only once. Not touching those 29 projects. And it all depends on the tooling, to be frank.

Everyone sees everything, right? Just think about a new junior engineer who joins your company and sees, hey, all the code is available. I can actually go ahead and check what my senior is doing. He's a back-end engineer and maybe I want to learn from him. And he can just go ahead and see the codebase, how a senior engineer has been writing code or how a principal engineer is writing a code. Easy to discover codebases, easy learning from the best practices. Because one thing when you work in a team is, you bring a lot of different ideas. When you work in a monorepo, you are sharing those ideas. And this is how you're actually helping your colleagues succeed. This is the standard practices. You can work as a team, discuss, and bring your monorepo to something new or make it more healthy.

Cross-team collaboration. This is what we started seeing. After we started working with 40 different teams, teams started talking to each other. It's not like, no, we are not enemies, we are actually friends. We want to achieve the same thing. If we are working on the same feature, why should we do it differently? Let's work together and figure out what is the best solution. And you can also identify your top contributors. You know, when you have repositories across 30 different repositories, you don't know who is actually contributing more. But with monorepos, you know the top contributor is AI. Just kidding. So, I'll just quickly go with the AI advantage because everyone wants to know what AI is changing. So, now, as per the recent studies, actually, more than 25 to 40% code is being written by AI.

I think we cannot deny the fact, because I have written code by hand last time, seven months ago. So, I know I have been using mostly AI. But AI needs context. Everyone knows that. Even though, yeah, sometimes we are confused, like, what context is. But it needs context. It needs something. And even the new softwares, if you think about any new library, for example, think about Angular or React, they are actually not creating new APIs for humans. They are creating new APIs for agents. They are saying the era of developer experience is gone. Now, it's the era of agentic experience. So, your agents should know the code better. Your agents should be able to understand the APIs. And that's where we are going.

And context switching is still a problem. If you're working in a polyrepo, this is how your day looks like. So, you start at 9 a.m., fix a bug in front-end repo, clone npm install, whatever, update API in your backend, different node version, different tools, then go to design system, build tool, different scripts. And then 3 p.m., you have your mobile app repo, where you go ahead and do something. And 5 p.m., you wonder, like, what I was doing, actually. And then you leave for the day. So, your day is over, you did nothing, if you are working in a polyrepo. And actually, this is the hidden cost of context switching. You need at least 23 minutes. This is not me, of course. This is like research done by experts who say if you are switching between multiple work, you need at least 23 minutes. I'm sure I need more than 30 minutes.

So, developer switch repos 5 to 10 times per day. This is very common in large organizations. And the time you are losing is 2 to 4 hours daily. And then mental overhead is you have to be aware of different commands, because npm, yarn npm, or npm, they have different commands, different environments, different CICD workflows, because you have to be aware, oh, how am I supposed to run linting here again? And then you are lost.

Different coding standards are causing significant overhead for various teams, especially when transitioning junior engineers between teams with distinct standards. The re-teaching process becomes a major challenge as each team follows different coding practices. This results in a substantial annual cost of 50K per developer in lost productivity within a polyrepo environment.

The primary obstacle for AI lies in context limitation. AI lacks visibility into backend API contracts, shared library implementations, and past issue resolutions. It remains confined to the boundaries of the current repository, unable to access a holistic view. In contrast, a monorepo environment offers AI a comprehensive perspective, enabling it to understand API implementations, backend languages, shared library patterns, issue resolutions, and dependencies across the entire graph.

Moving to a monorepo enhances AI capabilities by providing deep contextual insights and precise recommendations. AI in a monorepo setting gains knowledge of diverse languages, business logic spanning frontend to backend, and the ability to offer accurate suggestions. By leveraging the rich contextual information in a monorepo, AI agents can significantly improve their coding suggestions and understand the broader business and technical landscape.

Now you can say, oh, I just asked my AI, go ahead and refer to this repository, it does a good job. But you are overflowing your context window. It's not helping. It's actually just hitting your context window. With monorepo, your AI gets the entire picture. It takes your it knows your API implementation. It knows which language you are using for your backend. It knows your shared library API patterns. It knows how other teams are solving this issue. And it has access to your entire dependency graph.

Now, the latest tools are, you know, with harnesses, it's easy for AI to go ahead and figure out your dependency graph even. It knows how I can write new code in a better way. Because it knows your dependency graph. And it's understand your business logic from frontend to backend. Because AI is not your normal full stack engineer. It knows all the languages. It doesn't restrict itself to just a node or C sharp or Java. It can write code in any languages. And if you move to AI, sorry, monorepo today, you are actually just making your AI agents much better by giving this deep contextual and accurate suggestions.

So context is what we need. Simple example, for example, you have an API calling from your frontend. But actually, in reality, so this is from our real use case where we tried to call an API. In monorepo, we realized, Oh, this API is actually deprecated. We were documenting it. We were supposed to make it on production. But we realized, okay, this is deprecated, why we are using it. So simple example, AI can also see your breaking changes across. So it can tell you that something might break if you do something, because it has big picture of your code base. And AI can learn from your organization. I am 10 minutes over.

But I think, yeah. And AI can actually get 10x more accurate. If you give it complete picture, it means better understanding your codebase, learn from past mistakes, because it knows your past commits, past, you know, decisions you have made, best practical knowledge or best practices about your codebase, and it knows your dependencies. So it is aware of everything. And it's also easy to analyze, right? If you want to go ahead and ask, like, oh, I'm planning to do this, give me the whole picture, like how it will look like from frontend to backend, it can do that for you. So I'll just stop my talk here, because I'm just going over the time. But in case you have any questions, we can actually take that. I'm not talking about tooling specifically, because there are so many toolings available. If you want to discuss some tooling, I'm happy to talk about it later on. But yeah, I'll stop my talk here. Thank you. Thank you. Thank you so much.

Yeah, so basically, let's continue where you more or less just stopped your session. It's all about context, right? About using AI in PolyRepo or Monorepo. And I think there are two very similar questions. Basically, questions slash concerns. You mentioned only good parts of having Monorepo in context of AI context, right? But there are always pros and cons, right? And context is extremely expensive today. So with more context, you have more tokens, definitely more knowledge. And what could be some things to care about when you specifically build your context layer in huge Monorepo? Tell us. So there are multiple ways you can actually go about it. So you have all the AI tools, they have their own instructions file. That's the best way. You actually go ahead and do that. You can actually define your instructions based on your Monorepo projects as well. So you don't need to limit yourself. Say, OK, I will just put everything into agents.md. You can go to your projects and put a file there. Agents know how to read those files. So that's the best way to do it.

Split your instruction across different parts of Monorepo. I believe every major code assistant is supporting something like that. So I mean, do not load everything at once. Yeah, exactly. Or your main recommendation. Yep.

The next question that really resonates, looking at the number of people who... Wait, sorry. Oh, I think I clicked the wrong button. Let me try to find that. But anyway, I remember, I remember the question. The question was about in a big Monorepo, there could be different pieces of your project that require different permissions, different compliancy rules. How do you handle that complexity? I mean, so to give the access, for example, Code Honest file is very useful. Like you know which part of the project is owned by... I think it's come to ownership, right? And Code Honest does a very good job. I know it's not a perfect tool. I mean, we had it and then we were still struggling with it.

I think GitHub can still do better. If you have recommendations, I think when I was working at Solanus, we gave a lot of recommendations to improve Code Honest. But if you have recommendations, just go ahead and talk to GitHub. Hope they improve it. Apart from that, toolings can do a better job. For example, NX or TurboRepo, they help you identify what projects have changed. So, you know, you can build your own custom tooling on top of it. I have seen a lot of friends actually doing this with TurboRepo because TurboRepo gives you webhooks. So, you know, you identify, okay, this part of the project has changed. And for this project, I'm doing something custom. So you can run your commands. With NX, also, you can do the same.

With NX, also, you can do the same. Cool. So, yeah. By the way, I also see this as a strong trend that companies create more and more internal tools. And many of them are also somehow related to AI. And we can call this your external harness layer over your generic code system you mainly use. Yes, and the same questions about context. Let's pick this one. CI is extremely slow in Monorepo. It can be solved with proper concurrency, but then becomes expensive with hundreds of changes per day. How do you solve that? Yeah, so, you know, we had the same problem once we started growing our Monorepo at Selonis. So at some point of time, we had like reached 5 million lines of code. And we had 400 projects. So 400 projects, and we had like hundreds of ERs per day. So we decided to go with something known as MergeQueue. It's actually a feature of GitHub. You can enable it. It's available for enterprises. So what MergeQueue does is you can actually merge multiple PRs at once. So you know, what you can do for PRs, when you raise a PR, you can actually just run the minimum required tasks. And when they are promoted to MergeQueue, do the heavy lifting there. For example, running your end-to-end test, which is always expensive. And MergeQueue, you can define the queue size from 5 to 10. I think 10 is something which is recommended. So in that case, 10 PRs run this end-to-end test once, which is much faster than actually running 10 times end-to-end test again. So MergeQueue, there are multiple products available. If you don't want to go ahead, go with MergeQueue. From GitHub, there is Mergify. And there is one, trunk.io. So these are two different tools or products available as well.

Thank you so much. Very specific and practical recommendations. So let's mark this as answered. Yeah, I think we just went through these permissions. Context, again. If we have time, we will go back to the context, but I see the next question is resonating. Let's put it here.

In my experience, our monorepo with around 1.5 million lines of code in the back-end and half of that in the front-end hits the context limits really fast. Again, we go back to context. In that case, could polyrepo work better? I think I would like to defer here because we had our own monorepo with 5 million lines of code, and it was not even back-end. It was entire front-end code, 5 million lines of code, including our test, end-to-end test, unit test, and your front-end. And we never got this issue because it actually, when we started using AI, we realized, okay, it's causing our context limits to be a problem. And then we started writing custom instructions for each project. So it is not loading everything at once. It is just taking into context what we need or the project needs. So that's the best way to go. I know this is the biggest problem. So we have been there.

Because one of the questions was specifically, do we need to somehow restructure the whole project? Most likely not, right? It's just restructuring of your instruction across these multiple projects, right? That's something which you need to figure out. For example, NX gives you something known as dependency graph. So you know how the projects are related. If your dependency graph is a mess, then the first thing which you should do is untangle those dependencies. And then you have proper, clear dependencies, and then your AI does a better job because it knows what projects to actually consider when you are making changes. Yeah, sounds like great advice. Fix basic things first, and only then think about what to fix for AI. Exactly. Yes, I think we can mark this as red.

Next one about context, but let's go for this one. How do you best migrate from complex PolyRepo hell to a simpler monorepository without rewriting everything from scratch? Very good. Good question, by the way. This was one of the slides, but I decided to skip it. But very good question because we did that. So what we decided to do is we decided not to actually do a big bang migration. So everything is stuck and no one is able to ship. So what we did is we took few projects. We took few projects, big projects, and we said, hey, we are migrating it for you. Let's do this for you. So because you're a big project, other people will get more confidence that it works. And then we started doing incremental migration. And it's again totally depends on how you plan your migrations. So you have to make sure the old way of working is not stopping. So we decided to go in that way. We said, okay, we will continue this one, but we will make sure the old way of shipping projects is not stopping at all. And then we, believe me, took us more than a year. So it was not like a week job. We had 30 projects and we had to go out and convince, talk to everyone, fix their issues. And it took us more than a year to finally migrate everything. Of course, business should not stop. Exactly. Because, yeah, I think about this continuity. Thank you so much, my friend. Thank you. Thank you so much.