What You Need To Know About npm Workspaces

The newest major release of npm came out in October this year. Together with it came one very anticipated feature: npm Workspaces.

Workspaces are a way to work with repositories that have multiple packages - more than one package.json file. These projects are also known as monorepos.

But npm is a bit late to the party. Managing monorepos is already possible with other package managers such as Yarn and pnpm. Libraries like Lerna also bring swift tools to work with multi-package repositories.

That being said, npm Workspaces are still a step in the right direction.

What changes with Workspaces?

If you have a single package.json on your repository, you will not need Workspaces and nothing is going to change for you.

In multi-package repository, npm will now scan your folders looking for other packages and dependencies to install. This was made possible after changes made to Arborist, npm's dependency tree manager.

Duplicated dependencies across packages will be hoisted. This means they are going to be stored on the top-level of the packages. This is done mainly for performance reasons - we all know how big node_modules can get.

Using Workspaces

You can try Workspaces today by updating your npm to version 7. To update, run this command on your terminal:

npm install -g npm@7

Version 7 is still not marked as latest, so running npm install -g npm will still install 6.x.

If you install Node.js 15 today, it should already come with npm 7.

You can create a minimal monorepo setup to play around. Here’s an example of how a simple repository structure would look like:

.
├── package.json
└── packages
    ├── package-a
    │   └── package.json
    └── package-b
        └── package.json

A package.json file on the root of your repository is still needed, even if you don't have any dependencies there. On that file you will tell npm where your subpackages live by adding the workspaces entry:

// ./package.json
{
  // ...
  "workspaces": [
     "./packages/*"
  ]
}

With this, when you run npm install on the root, npm will be smart enough to install package-a and package-b dependencies.

I made a GitHub repository with this example if you wanna check it in more details. Here’s the link: npm-workspaces-demo.

Are Workspaces ready?

“Should I change all my code to use npm Workspaces?”

Workspaces are definitely a welcome addition, but a bit more work is needed to make it a complete solution for managing monorepos.

As of the writing of this post, it still hasn't reached feature parity with Lerna, pnpm or Yarn Workspaces. Technical details about how Workspaces will work are still being voted and discussed on GitHub issues.

The toolset is still limited. There is no npm workspaces subcommand or anything equivalent. If you want to be an early adopter, you’ll need to combine it with tools like nx or Lerna for a complete monorepo workflow.

npm Workspaces vs. Yarn Workspaces

Yarn is the second biggest package manager for JavaScript, so it might be fair to make a comparison.

Yarn Workspaces is around for much longer (it was launched somewhere around 2017). It is a complete feature. The yarn workspaces interface already gives you the tooling that npm is still missing. npm Workspaces is still an MVP.

My personal opinion is that npm Workspaces shouldn't differ that much from existing solutions like Yarn Workspaces - it even borrowed the "Workspaces" name! I believe we can expect a similar API and an easy way to switch between other implementations (but again, that's an opinion).

What’s next for npm Workspaces?

We can expect new things to come for Workspaces. It will not be just an improvement to the npm install command (source).

On GitHub discussions you can see that Workspaces will evolve in a way to bring tools for a more complete workflow.

If you want to keep up-to-date with Workspaces development and new features, there are a few things you can do:

• Watch the ongoing Workspaces RFC discussions on this repo;
• Keep an eye on the npm Blog for new releases;
• Subscribe to hyperfoo.io's newsletter, where I will publish a fresh new article about the next Workspaces iteration. :-)

Thanks for reading!

Cover background by Paweł Czerwiński on Unsplash