nrwl / monorepo.tools

Your defacto guide on monorepos, and in depth feature comparisons of tooling solutions.

Monorepo.tools

Monorepos are hot right now, especially among Web developers. We created this resource to help developers understand what monorepos are, what benefits they can bring, and the tools available to make monorepo development delightful.

There are many great monorepo tools, built by great teams, with different philosophies. We do our best to represent each tool objectively, and we welcome pull requests if we got something wrong!

The tools we'll focus on are: Bazel (by Google), Lage (by Microsoft), Lerna, moon (by moonrepo), Nx (by Nrwl), Rush (by Microsoft), and Turborepo (by Vercel). We chose these tools because of their usage or recognition in the Web development community.

Development

This project was generated using Nx, check Nx's documentation to know more.

Running locally

To run monorepo.tools locally, run the following command:

nx serve website
# Same as
nx run website:serve

Contributing

See contributing document.

monorepo.tools's Issues

Evaluation Criteria: Vendor lock-in, complexity & ease of learning

Hello, I recently discovered Understanding Monorepos and it's a great resource for people who want to get an overview of the current JavaScript monorepo landscape.

I've been using monorepos with Lerna myself for the past 3 years (Example: wire-web-packages) and am currently examining Turborepo and nx. I noticed substantial differences compared to Lerna and I think these should be highlighted in the tools review.

What I really like about Lerna is how easy it is to get started. Lerna just sits on top of plain npm packages and gives you the possibility to link them together (lerna bootstrap) and run npm scripts in all of them simultaneously (e.g. lerna run --parallel build). On top of that, it can make use of Yarn Workspaces and streamline the release process (lerna publish). If you are already familiar with npm packages, you will quickly find your way around Lerna.

The same applies to Turborepo. You can actually use Turborepo in connection with Lerna and benefit from Turborepo's improved task scheduler (read more here). In a Turborepo monorepo, you will also have all your individual packages with their package.json files (see here). This makes it easy to switch tools if they are discontinued because you will still have standard npm packages.

As you can see, Lerna and Turborepo have an easy learning curve because you can achieve a lot if you are already familiar with standardized npm packages.

The situation is very different with nx. When starting out with a simple npx create-nx-workspace --preset=react you will get introduced to Nx Cloud and Nx CLI. Once the monorepo is then created, there are no more individual package.json files (it's actually the most requested nx feature). Instead you will be left with project.json files and/or a monolithic workspace.json file. That being said, the mental model is different from standard npm packages. You will also have to learn about executors, generators, and plugins.

On top of the different namings ("package.json" becomes "project.json", "scripts" become "targets", ...) there is a large dependency in the execution of commands. For example, linter packages like eslint are wrapped in packages like @nrwl/eslint-plugin-nx and should be executed through @nrwl/linter:eslint.

What was once:

"scripts": {
  "lint": "eslint --ext .js,.ts apps/yolo-e2e"
}

Now turns into:

"targets": {
  "lint": {
    "executor": "@nrwl/linter:eslint",
    "outputs": ["{options.outputFile}"],
    "options": {
      "lintFilePatterns": ["apps/yolo-e2e/**/*.{js,ts}"]
    }
  }
}

In addition, nx is very opinionated and comes with a .eslintrc.json that makes use of vendor-specific plugins such as plugin:@nrwl/nx/typescript. I see the benefit of it (sensible defaults, compatibility of tooling, bundled updates) but it also requires increased training time and makes it hard to move back to standard npm packages (which is why I see a vendor lock-in here).

I am currently missing my mentioned differences in the tools review. Complexity, vendor lock-in and ease of learning should become additional evaluation criteria as these can influence the decision for a monorepo system.

[CONTENT] Consider adding Polylith

Consider adding the tooling support for the Polylith Architecture. As of this writing, there's tooling available for Clojure and Python.

Docs about the Polylith architecture in general: https://polylith.gitbook.io/polylith/

The tooling for Clojure: https://polylith.gitbook.io/poly
The tooling for Python: https://davidvujic.github.io/python-polylith-docs/

I would be happy to help out with this.

Pants now supports visibility rules

Pants now supports visibility rules in a manner similar to bazel. More info: https://www.pantsbuild.org/2.21/docs/using-pants/validating-dependencies

Consider adding Pants to the list of tools

Pants is a polyglot open source monorepo build system. It currently supports Python, Go, Java, Scala, and Shell. Adding JavaScript support is high on the community roadmap's priority list. Pants is a BUILD-file oriented system with a design inspired by Blaze, Ant, and others. It is most frequently compared to Bazel; which is reasonable, though there are a number of key differences between the two: https://blog.pantsbuild.org/pants-vs-bazel/

More info is available at https://pantsbuild.org and https://slack.pantsbuild.org. As a team member, I'm happy to answer questions. Thanks for welcoming the project to be submitted for your consideration! https://twitter.com/juristr/status/1514642911492640771?s=20&t=-YfS5beID6oxDqQhLM83zQ

Include `please` build tool

The please build tool would be nice to have represented.

[CONTENT]

https://monorepo.tools/#monorepo-features
https://monorepo.tools/#monorepo-tools

In monorepo-features, multi-language support is very important to consider. Front-end, backend, and devops must be in the same repo, but are typically not written in the same language.

Nix should be added to the list of monorepo tools as it addresses some of these challenges.

Content feedbacks

Hi! I just discovered this and it's honestly a good reading, especially the references and articles are pretty useful and I wished I had this when I started my journey into monorepos :) I'll try to leave aside things related to #18, but I believe some might be entangled, so sorry already.

1. npm monorepos vs others

It looks like the website has some bias towards npm-oriented monorepos (...because it's made by nx?).

The fact that Bazel is a truly language agnostic monorepo seems totally eluded under a simple "Consistent tooling" umbrella which consists of a single sentence but imho this is a major point to look at when searching for a monorepo solution.

At the time I've started my researches, this was probably the biggest point of decision: we had a tree of "npm/non-npm" monorepo solutions, and then either Bazel/Buck/Pants/Please or lerna/nx/rush. The questioning was mostly in planning, setting up, maintaining our monorepo. I'm not sure if you tried to setup a Bazel/Please monorepo but it is light-years away from setting up a nx/lerna/rush/turborepo monorepo which, even though are quite different between themselves, look all pretty similar compared to those non-javascript monorepos.

Either Bazel should not be here, or either imho you should have a separate section describing the pros/cons of Bazel-type (let's say BUILD-file based monorepos) vs more integrated/opinionated npm-oriented solutions. You may argue that "nx is pluggable" but a user would still carry the node runtime to build your stuff anyhow, where solutions such as Please have portable binaries to avoid such a cost (i'm talking about the monorepo toolchain, not the project's ones). On the other hand, by nature npm-oriented solutions will have greater focus/capabilities in caching dependencies because there's a greater relationship to npm, where broader monorepos would just elude this and delegate to either a language-specific toolchain or the build script itself. It's a game of pro and cons, but it should be stated.

...and if Bazel is here, i guess it's fair that related competition should also be represented: Buck, Pants, and Please (to only name those I've tried).

2. eluded pricing

There's also a great shade around the "opacity" of the toolchain and the features which claim to be available but not mentioned if free or paid. I think that, if you truly want to be informative you have to be impartial and shouldn't hide that some of nx and turborepo features are part of a paid plan. One of the major reason why we didn't choose nx at the time was the learning curve and the necessity for a staff to learn a framework - i think that nx is much more an hybrid of monorepo/framework due to the tons of generators/etc which come with (not that i dislike it personally, but it has to be said).

---

I realise typing this that it's a lot already so i'll stop there. Happy to help.

Consider adding section about VCS

Monorepos tend to become very large and optionally have large binary blobs in them (for example art content in gamedev). So different VCS should be considered. For example git as-is is not suitable for large binary objects, etc. Also, it would be great to talk about integration of VCS and build system such as to be able only to checkout folder of particular projects and all of their dependencies.

[CONTENT] Provide information about CI/CD integration

It would be great to have an overview how the listed tools can be integrated in a CI/CD pipeline.
I don't think about concrete implementations but about general things that should kept in mind such as:

• running/testing only parts of the pipeline for affected packages
• test everything in a single pipeline
• deploying only affected packages
• Distinguish between a branch pipeline (run only affected and a master/main branch pipeline)

[CONTENT] Consider adding Moonrepo

Hi, I've been exploring Moonrepo for monorepo tooling and I thought it would be nice to have them represented in this website.

Integrate Yarn 3

Hello,

I just found your website after integrating a monorepo with Yarn 3, and I feel it could compare against other solutions. I would understand why Yarn 1 or 2 are not present, but is there a specific reason Yarn 3 has been omitted?

Thank you for your great website and have a nice day,
Adrien

[CONTENT] "Multi-repo" instead of "Polyrepo"

Multi-repo is a better term for the alternative to polyrepo.

• Based on github searches multi-repo is used a lot more than polyrepo (Google as well, including other popular contributors calling it this)
• Poly- prefix has confusing similar terms, e.g. a polyglot speaks multiple languages, so a polyrepo might be a repo with multiple languages
• Multi- however has terms like multiplayer, makes people instantly think "multiple repos"

Although the choice to hyphenate or not is confusing.

Which section?

https://monorepo.tools/#polyrepo-concept

What was there before?

A “Polyrepo”
For the sake of this discussion, let's say the opposite of monorepo is a "polyrepo".

What are your modifications?

A “Multi-repo”
For the sake of this discussion, let's say the opposite of monorepo is a "multi-repo".

[CONTENT] Add a new row to the tools review table

First of all, let me thank you for this project!

I'm a big fan of monorepo and now I have a website I can share with people when they're new to the concept.

As per subject, I'd love to add a row (probably in the manageable section?) to the tools review table to explain which tools support more than one language out of the box.

I think that's critical when evaluating monorepo when multiple programming languages are involved (I wrote about this here) and the only thing I feel it's missing to fully capture the state of monorepo tooling.

If you like the idea, I can contribute to it myself (I would love to!). I would call the row "polyglot" but that clashes with existing terminology so I'd probably use "multi-language" (or whatever you find more appropriate).

[CONTENT] Release Management in Monorepos

Hey @juristr @bcabanes ,

Thanks for the amazing content on this website.

While I was browsing this, I realize there is a lot about building management systems, but one thing that I think gives a lot of interesting problems to solve is release management. Monorepo doesn't necessarily mean it's only a trunk deployment model for all apps/services.

For example, Nx is doing the release of all packages at once:
https://github.com/nrwl/nx
But Airflow or BlueprintJS are doing multiple package releases from their monorepos using git tags or Releases:
https://github.com/palantir/blueprint (20+ packages)
https://github.com/apache/airflow/ (60+ packages!)

This creates interesting problems regarding which approaches would work the best for the different use cases and engineers.
At least for me, this is the biggest gap, in the content on the website as it creates interesting maintenance challenges.

Thanks