Monorepos are great, until they aren’t.

You can think of them as beautiful sand castles on the beach. Some people build amazing castles with lots of care, I even saw one with running water once (don’t ask me how that thing worked). And then a kid comes running by, thinking it’s a toy castle and jumps right in.

Long story short, the castle is no more, the kid’s looking around with a big “WTF” look on his face, the person who built the castle is still in shock and the mother of the child running with an expression of “what the hell did my kid do now” towards the scene.

Do you want your monorepo to be the next sand castle? Because I don’t.

These are the 5 most common problems I’ve found with monorepos and my suggestions on how to either fix them or prevent them from ever happening.

Let’s try to keep that kid from even getting closer to your sand castle!

A broken master/main

A broken main branch is what happens when people start merging incorrect branches back into it and you realize it three weeks later due to a bug in production that was supposed to have been fixed a while ago.

This can happen due to many reasons, but since we’re dealing with a monorepo, chances are, you have multiple teams working on different projects and they’re not aligned around their branching model and the boundaries that exist between projects.

One of the advantages of monorepos is that sharing code becomes quite easy, after all, you can just put the common code into a shareable project and import it from there.

The problem with that? It blurs the boundaries and it invites everyone to affect those common folders however they see fit. Maybe they need a bug fix? They can just go ahead and do it. Do they need a new feature? Sure! Added right in. Or perhaps change a feature that already exists to make it work for them? Sure, why not? Nobody is using it anyway!

I can keep going with the examples, but my point is, that uncontrolled access to the main branch coupled with an uncertain branching model can cause real havoc for a monorepo. Especially so if there are multiple teams and projects involved with it.

How can you fix it?

To me, this is not a problem you can solve with tools, but rather, with knowledge. The root cause of this particular issue (and I’ve seen it first hand) is a lack of coordination and understanding of how Git works and how each team member needs to interact with the repository.

I’ve seen teams solving this by educating their developers on how Git works and how to solve problems with it. And I’ve seen others writing custom documentation showing exactly the steps required to start and end a task within their workflow.

It’s really up to you to decide, based on your team and their skills, how to proceed. But make sure everyone’s on the same page before moving forward, otherwise this problem will happen again.

Too many cooks in the kitchen

Similar to the previous problems, sometimes it is not about people not knowing how to use the tool, but rather about the lack of a central figure of authority that decides how to deal with the repo.

You see, if you don’t have a clear set of rules, you’ll most like end up landing on the previous problem anyway. Mostly if your monorepo is home to multiple projects handled by independent teams (in the sense that they’re not the same team dealing with multiple projects).

Usually when a team starts a project, they have to agree on the standards they’ll use as part of their dev workflow. I’m talking about coding standards, tabs vs spaces, semicolons or no semicolons, and of course, branching strategy.

But what happens if each team decides on their own how to handle branches and no one coordinates with each other but they’re all using the same repository with the same main branch? I’ll tell you what happens: chaos.

The solution?

As you’ve probably guessed, there are two ways to handle this situation for a monorepo:

1. You make sure you coordinate with all other teams. Sometimes creating some sort of central authority to decide on standards and common workflow. This authority might have someone from each team to make sure no one is left out and that every project’s best interests are looked after.
2. Or you can simply decide that there is no single “main” branch, and you define multiple parallel trees using a smart branching model. This technique can work well if each project is independent of the other, especially if they’re using different technologies, because that would mean there is zero chance for them to share code with each other.

Depending on your situation you’ll want to go with option #1 or #2, but make sure that if there is common logic/code between projects, coordination is a priority for everyone.

Coupling between projects

This is a common complaint about monorepos.

Your projects will end up coupled with each other to the point where you can’t really affect one without affecting the rest.

It’s true, it CAN happen, but it doesn’t have to.

Why would this happen? Because you have multiple projects that can feed off each other. Essentially, you’re having a lot of common code, and you’re having your projects reach into each other to grab the code they need.

That for sure will couple them to the point where they become a single mega project.

How can you fix this?

I like to say it like this “promote extensibility over reusability”

In other words, when you have a piece of code that might be useful to others, share it in a way that you’re only sharing the barebone structure of the logic, the common part, and you and everyone else wanting to use it, has to implement the bit of logic that is particularly useful to them.

So instead of forcing your own logic and way of working onto other projects (potentially coupling them into yours), you are giving them the common building blocks for them to extend and gain the actual time-saving benefit without having to work as you do.

Think for example, of a logging library. You’ve built your own library that logs information with multiple levels and that, in your case, sends the data to Splunk, because your team has an account on that platform.

However, every other project might not have a Splunk account, so instead of sharing that part with them, allow them (and you) to extend your library to code the particular log-storage solution they might want to use. That way projects aren’t coupled, but logic is shared.

Individual releases can be difficult

Deploying a single project per repository is easy, setting up an automated CI/CD workflow for it is almost trivial.

However, when you have a monorepo, that becomes a bit less trivial, especially if you’re building a set of libraries that each one needs to be independently released.

How do you version each library and how do to keep them individually shareable while at the same time, living inside the same repository? If you’re doing the work by hand, that’s definitely a possibility.

Of course, the more libraries you have, the harder it’ll be to get each release done without accidental mishaps and incorrect versions being published.

The point is, that you should be able to automate and control the way you release independent versions of your libraries.

How do you fix this?

Lucky for you there are many monorepo tools out there that can help you. Some of them will require you to adapt to their proposed workflows, and others might need a bit of setting up before properly working.

That said, in the past I’ve used Bit, and it’s worked quite well for me. I was having a set of libraries that had to be published into NPM individually, but they all lived inside the same repository.

Thanks to Bit, I was able to tag them, version them and release them individually without having to worry about anything. And on top of it all, once I realized there was common logic to share between each of them, I was able to extract and version that code easily with Bit as well, since it was able to version and publish a subsection of one of my projects as if it was another individual library.

Big build times, making small changes required to build the whole repo

The last problem is also quite common if you haven’t handled monorepos in the past.

This is hardly the case for repos where you’re only building libraries (i.e independent projects), but if you’re developing a big application where you have multiple front-end modules, the back-end and probably some other service inside it, and you want to change a typo in your home page, you might need to rebuild the entire thing.

Now, maybe that takes 5 minutes, or perhaps just 1, but imagine going through it every time you make a small change. The development times increase significantly over a week or even a month.

Not to mention that the terrible developer experience will cause some frustration on the dev going through it.

How can you fix this?

Lucky for you, this problem is easily fixed by the use of smart tools. Or in other words, tools designed to manage monorepos.

I’m talking about using a proper bundler for your front-end (if you have one), and tools like TurboRepo or Bit even (which I mentioned already). These projects were born out of the need to improve the developer experience while dealing with monorepos, and you should be taking advantage of that, instead of refusing to learn, yet, another tool.

Setting up build steps for each project, and properly watching for changes in the right place can mean the difference between spending 2 hours a day just rebuilding the project, and having those extra 2 hours to work on the problems you have to fix.

Monorepos are very handy and can help create very agile development workflows. But just like with any methodology, you have to make sure you have a properly trained team and that everyone’s using the right set of tools. Otherwise, you’re asking for trouble.

Have you run into any other problems with your monorepo in the past? Share it in the comments, I’d love to know how you solved them!

Go composable: Build apps faster like Lego

Bit is an open-source tool for building apps in a modular and collaborative way. Go composable to ship faster, more consistently, and easily scale.

→ Learn more

Build apps, pages, user-experiences and UIs as standalone components. Use them to compose new apps and experiences faster. Bring any framework and tool into your workflow. Share, reuse, and collaborate to build together.

Help your team with:

→ Micro-Frontends

→ Design Systems

→ Code-Sharing and reuse

→ Monorepos