What is Monorepo? A straightforward explanation

@ Technical Discussion

Introduction

As the complexity of development increases, the term Monorepo frequently appears, yet resources explaining it are scarce. I aim to clarify my understanding of Monorepo.

What is Monorepo? Why do we need it?

To understand Monorepo, we can start by analyzing the problems existing solutions face, and then extend to the Monorepo solution.

Multi-Repository / Polyrepo

When creating a new project, the intuitive thought is often “let’s create a new Git repository.” This approach works fine for small projects, but as the project scales, it can lead to various issues, such as difficulties in managing or updating shared logic, types, configuration files, or packages across different applications. If you want to synchronize shared code snippets, you need to publish packages specifically, and then other projects must track updates through package management tools.

This approach is not problematic per se, but it is clearly not suitable for frequently updated projects:

  • Requires additional package publishing
  • Every package update necessitates updates to “any” dependent items
  • Needs to manage package versions across “all” repositories
  • Requires switching between different repositories
  • CI processes are less convenient
  • Difficult to roll back system states

Monolith Repo

From another perspective, if all interdependent repositories are placed in the same repository, wouldn’t that solve the problem? This approach is: “just shove any project into the same repository.” Although it seems counterintuitive, it does solve the issues brought by multiple repositories! However, this approach can lead to a large project where changes in one part affect the whole, and it lacks flexibility in technology choices (due to shared package management).

Ultimately, there are still challenges regarding scalability, maintainability, and flexibility:

  • Code interdependencies can lead to merge conflicts and collaboration issues
  • Any change requires retesting or redeploying the entire project
  • Package management lacks flexibility
  • Large project size causes performance issues
  • Permission management issues

Monorepo

Monorepo
├── apps
│   ├── frontstage
│   │   └── package.json
│   ├── backstage
│   │   └── package.json
│   ├── ui
│   │   └── package.json
│   └── design-system
│       └── package.json
└── package.json

Similar to Monolith Repo, it is also “just shove any project into the same repository,” which can easily be confused with the Monolith approach. The difference is that each repository is still treated as an independent project within the package manager, which can be managed through package manager settings🔗 or tools like Nx with TypeScript Project References🔗.

This approach primarily improves the inflexibility of package management by managing shared dependencies at the root level while still allowing each project to have its own independent packages. However, challenges regarding scalability, maintainability, and flexibility still need to be addressed with other tools 😑.

Monorepo Extensions

Due to performance, permission, collaboration, and other issues in both Monolith Repo and Monorepo, other tools are typically used to address these problems, such as: rush🔗, Nx🔗, Turborepo🔗. These tools enhance the experience by sharing caches among teams to avoid redundant executions, parallel execution, and automating dependency updates.

Summary

Advantages of Monorepo

  • Easy code sharing
  • Simplified dependency management
  • Small changes become easier
  • Easy large code refactoring
  • Easy cross-project collaboration for teams
  • Unified CI process

Disadvantages of Monorepo

  • Additional learning and maintenance costs
  • Performance issues
  • Permission issues

The difference between Monorepo and Monolith Repo lies in the flexibility of managing multiple packages. If there are frequently shared code snippets or packages between projects, then Monorepo is a good solution to consider. However, if there is not much interrelation between projects, using Monorepo may increase unnecessary complexity, and it is advisable to consider using multiple repositories.

Further Reading