1. Workspaces

Workspaces are a new way to setup your package architecture that’s available by default starting from Yarn 1.0. It allows you to setup multiple packages in such a way that you only need to run yarn install once to install all of them in a single pass.

Why would you want to do this?

• Your dependencies can be linked together, which means that your workspaces can depend on one another while always using the most up-to-date code available. This is also a better mechanism than yarn link since it only affects your workspace tree rather than your whole system.

• All your project dependencies will be installed together, giving Yarn more latitude to better optimize them.

• Yarn will use a single lockfile rather than a different one for each project, which means less conflicts and easier reviews.

How to use it?

Add the following in a package.json file. Starting from now on, we’ll call this directory the “workspace root”:

package.json

{
    "private": true,
    "workspaces": [
        "workspace-a",
        "workspace-b"
    ]
}

Note that the private: true is required! Workspaces are not meant to be published, so we’ve added this safety measure to make sure that nothing can accidentaly expose them.

After this file has been created, create two new subfolders named workspace-a and workspace-b. In each of them, create another package.json file with the following content:

workspace-a/package.json:

{
    "name": "workspace-a",
    "version": "1.0.0",

    "dependencies": {
        "cross-env": "5.0.5"
    }
}

workspace-b/package.json:

{
    "name": "workspace-b",
    "version": "1.0.0",

    "dependencies": {
        "cross-env": "5.0.5",
        "workspace-a": "1.0.0"
    }
}

Finally, run yarn install somewhere, ideally inside the workspace root. If everything works well, you should now have a similar file hierarchy:

/package.json
/yarn.lock

/node_modules
/node_modules/cross-env
/node_modules/workspace-a -> /workspace-a

/workspace-a/package.json
/workspace-b/package.json

And that’s it! Requiring workspace-a from a file located in workspace-b will now use the exact code currently located inside your project rather than what is published on Github, and the cross-env package has been correctly deduped and put at the root of your project to be used by both workspace-a and workspace-b.

How does it compare to Lerna?

Yarn’s workspaces are the low-level primitives that tools like Lerna can (and do!) use. They will never try to support the high-level feature that Lerna offers, but by implementing the core logic of the resolution and linking steps inside Yarn itself we hope to enable new usages and improve performance.

Tips & Tricks

• The workspaces field is an array containing the paths to each workspace. Since it might be tedious to keep track of each of them, this field also accepts glob patterns! For example, Babel reference all of their packages through a single packages/* directive.

• Workspaces are stable enough to be used in large-scale applications and shouldn’t change anything to the way the regular installs work, but if you think they’re breaking something, you can disable them by adding the following line into your Yarnrc file:

  workspaces-experimental false

Limitations & Caveats

• The package layout will be different between your workspace and what your users will get (the workspace dependencies will be hoisted higher into the filesystem hierarchy). Making assumptions about this layout was already hazardous since the hoisting process is not standardized, so theoretically nothing new here.

• In the example above, if workspace-b depends on a different version than the one referenced in workspace-a’s package.json, the dependency will be installed from Github rather than linked from your local filesystem. This is because some packages actually need to use the previous versions in order to build the new ones (Babel is one of them).

• Workspaces must be children of the workspace root in term of folder hierarchy. You cannot and must not reference a workspace that is located outside of this filesystem hierarchy.

• Nested workspaces are not supported at this time.