Still Not Using a MonoRepo?!?

What is a MonoRepo?

A monorepo is an architectural concept, by which instead of managing multiple repositories (projects), we keep all the isolated code parts inside one single parent repository. For example, if we have a system comprising of a couple of microservices and a frontend, under a monorepo we would have the following structure:

/monorepo-root

    /apps

        /web-frontend

        /e2e-testing

        /microservice-a

        /microservice-b

    /libs

        /shared-models

        /common-services

    package.json
 
    ...other project files (tsconfig.json, .prettierrc, .gitignore etc.)

I’ve been a fan of using monorepos for a long time now, and in fact, almost every project I’ve delivered in recent years was monorepo based. Oftentimes I find myself needing to explain to clients the benefits of using a monorepo, but then when it clicks and they get it - they never look back, making it the new architecture structure of any new multi-app project they develop.

Benefits of a MonoRepo

Easy Code Navigation

As all projects are under a single parent folder, once opened in an IDE, navigating between projects and libs is natural and quick. This not only allows peeking into code quickly when developing thus expediting development, but also enhances code quality by having devs from adjacent projects review other devs code and even enhance it or fix bugs they find.

Code Sharing & Collaborating

Let’s say we want to use some common UI components between several separate frontend projects. Without a monorepo we’d probably package shared components together and ship them as an npm repo - but if you’ve been down that road before then you probably already know this is a painful process, and then when a bugfix or enhancement is required - the owner devs of that package in the organization will need to release a new version which usually means you’ll have to now wait until it is released.

What we need are quick changes, where every dev can consume and contribute to the UI components lib. This is exactly where a monorepo shines; since all projects are available under the monorepo then every dev can enhance the shared component with new functionality they need for their use-case.

Unified Code Quality and Practices

Prettier, pre-commit hooks, custom eslint rules and any other code quality tool can be used and enforced on all monorepo projects. This ensures the same code practices are enforced across-the-board on all projects, instead of having each project have its own “style”.

The benefit should not be underestimated - from my experience, having the same style/practices used in all related projects significantly improves code quality and maintainability and allows for quicker release cycles. Why? Because a developer that has seen one project will feel “at home” reading other projects’ code since they share the same structure, indentation and rules, and then of course - also deliver faster.

Tooling

A monorepo is not just a folder structure having a root and subfolders for apps/libs, a monorepo can provide extremely useful tooling. That includes scripts and commands to run/build several projects concurrently, enforce access strategies (which projects can import/consume specific libs) and dependency graphs which can indicate which projects need to be rebuilt once some other project’s code has been changed.

Save Time and Space

Using a monorepo allows you for instance to have a single package.json file for all projects. While that might sound intimidating, it actually saves time and space by having a single node_modules folder for all apps/libs, so a lot of the npm packages which are shared (remember that each package might have its own dependencies and so forth, which could amount to a considerable number of packages) are only installed once.

The Many Excuses (a.k.a. "Reasons") Why NOT

Over time I’ve worked on a lot of projects with many clients, and detected common themes of reasons why teams unfamiliar with the monorepo concept are reluctant to go forward with it. Here are some of these excuses:

“Some teams use native JavaScript while others use TypeScript” - Now that is a mishap indeed, as all JS projects nowadays should be using TypeScript. Still, if you insist, there is no reason why you can’t mix JS projects with TS projects in the same monorepo; heck you can even have Java and Python projects in the same monorepo. No reason not to (except that your organization’s devs now need to master few programming languages of course).

“I don’t want other teams touching my libraries’ code” - Firstly yes, this is for real… now why would you not want other devs in your organization to be able to peek into your code and contribute? Unless you’re working for the NSA or some other intelligence agency where secrecy across teams is acred, you should really want as much eyes on your code as you can. After all why has open source software flourished so much if it wasn’t for this simple idea?

“We’re doing fine working with single repos already, why switch?” - this sounds like pure laziness to me. Once you understand the benefits you’re going to rip simply by using a monorepo this no longer holds as an argument.

“We don’t have a lot of code to share between projects” - even if this is true (which usually isn’t since once you go monorepo you find yourself actually finding many code-sharing cases), then there are other benefits to a monorepo which you’ll be missing, as listed in the main article’s section.

Where Do I Start?

If you’re reading this then the ~900 words of this article so far have not been written in vain :-) 

My personal preference is Nx (and while you’re on that tab, do watch the 10 minute tutorial there - it is worth it). 

I won’t go into too much details here about Nx and why I chose it to be the go-to monorepo of choice for me for every project I’ve delivered in recent years, but I’m certain that for most readers it would be the perfect monorepo tool (and yes, I did use other monorepos, but eventually converged to using solely Nx).

PS: do drop a comment below if you’d like me to write a follow-up post on getting started with Nx.

-Zacky