Monorepos have gained a lot of popularity recently, especially among web developers. There are many resources that cover this topic, so I will briefly cover What is a monorepo and the benefits it provides. At the end I will cite the resources I used to get to this point.
What is a monorepo?
A monorepo is a single repository containing multiple distinct projects, with well-defined relationships. – Monorepo.tools
But a monorepo is about more than just code co-location because without the well defined relationships or boundaries, a monorepo can quickly become monolithic. And a good monorepo is the opposite of monolithic (Misconceptions about Monorepos: Monorepo != Monolith)
Why use a Monorepo?
The opposite of a monorepo is a polyrepo or multirepo; that is a new repo for each project, i.e.. “1 repo = 1 build artifact”. This approach is popular because it encourages team/developer autonomy. Developers can dictate their own tech stack, testing strategies, deployment, and (most importantly to them) who can contribute to their codebase.
Now those are all good things, but there are drawbacks to this multi-repo approach that most developers are aware of, but put to down to ‘that’s just how it is’. Drawbacks like cumbersome code sharing, significant code duplication and inconsistent practices, cross-repo collaboration problems, inconsistent tooling, dependency hell when updating, automation difficulties, scalability issues, and so on.
“… this autonomy is provided by isolation, and isolation harms collaboration” – Monorepo.tools
So how is a monorepo any better?
For starters, if all your related code is co-located, its much easier to manage dependency updates across all apps, the same shared libraries can be made available to all relevant apps and provide a single source of the truth. Tooling and coding standards can be enforced more consistently. Developers can work across different projects or components more seamlessly, facilitating better teamwork and knowledge sharing. Changes or refactoring that affect multiple components can be made in a single PR, ensuring that all related changes are coordinated and reducing the risk of breaking changes.
While monorepos offer these (and more) benefits, they also come with their own challenges, such as potential scalability issues with very large code bases, increased build times, the need for more sophisticated tooling to manage the codebase’s complexity. However, many organizations find that the advantages of a monorepo outweigh the disadvantages, particularly in terms of improving collaboration, consistency, and overall code quality.
Misconceptions
Misconceptions about monorepos (or any tool or technology) often deter teams from adopting this development approach. Lets shed some light on a few and expose the reality of using a monorepo.
Monorepos should contain all a company’s code
While large companies like Google or Facebook practice this behaviour it is not the norm. Many teams will only group very similar, closely related apps that can benefit from a shared workspace.
Monorepos mean all projects must be tightly coupled
Monorepos can still support modularity and separation of concerns. In fact many monorepo management tools will advocate for decoupling components and maintaining an modular architecture, otherwise the monorepo is just monolithic.
Monorepos lead to longer build times and slower CI/CD pipelines
With proper tooling and optimization, such as incremental builds and distributed CI/CD systems, build times can be managed effectively. Tools like Nx, Bazel & Lerna utilize incremental builds to only build affected components and caching to prevent building the same thing twice.
Monorepos are harder to scale
While monorepos do present unique scaling challenges, they also offer solutions for consistent and scalable development practices.
Monorepos are harder to secure
Security in monorepos can be effectively managed with proper practices. By only including related projects in a monorepo along with access controls, code reviews and CODEOWNERS can ensure that the codebase remains secure.
The Real Challenges
Just because the many misconceptions are manageable, does not mean monorepos don’t have challenges of their own, like migration complexity, tooling adjustments, and workflow changes. Proper planning and best practices are essential to navigate these hurdles and successfully transition to a unified codebase.
Migration Complexity:
Moving code from multiple repos into a single repo while ensuring dependencies are mapped and managed correctly can be complex, especially if projects have different histories, dependencies and configurations.
Tooling and infrastructure:
Not all your existing build systems, CI/CD pipelines or development tools are designed to handle large monorepos and may require significant updates or replacements.
Development Workflow Changes:
Ensuring the effectiveness of code reviews in a larger, more integrated codebase and adapting or redefining branching strategies to suit the monorepo setup while maintaining workflow efficiency
Cultural and Organizational Resistance:
Convincing a team that use to working independently to adopt to the new approach and workflow can be challenging. Resistance is common and training may be required while they adjust to the more integrated and collaborative development environment
Consistency and Maintenance:
Maintaining consistent coding standards, practices and docs will need to be applied across the repo. Managing and addressing technical debt will be more critical as the monorepo grows.
Learning Curve:
New team members may require additional training to understand the structure, tools, processes and workflows of monorepo management and development.
Final Thoughts?
Monorepos are not a silver bullet. And there will be challenges and trade-offs and a culture shift and training and yes, it will be a lot of work. But the benefits could far outweigh those challenges; less time worrying about boilerplate and config per project leads to faster turnaround time on new features or bug fixes, easier maintenance leads to faster adaption of the newer technology trends or tech stacks, more test coverage leads to a more stable product and better code quality which in turn leads to easier adaption by new developers and easier dependency maintenance and more.
Experiences with negative Monorepo research/posts
In my research I did find posts that describe negative experiences with monorepos. Posts that talk about how the benefits of monorepos are not so beneficial and that anyone using a monorepo should abandon all hope. However, nothing stirs up a the software community like telling them that a technology they are using is just the worst. So it’s the comment sections of these post that are more valuable than the articles, with developers denouncing the article and coming to the defence of monorepos, posting how they were able to overcome, mitigate or avoid the problems that the original author encountered.
