npm command-line interface

# workspaces

Working with workspaces

## Table of contents

- Description
- Installing workspaces
- Using workspaces
- See also

### Description

Workspaces is a generic term that refers to the set of features in the npm cli that provides support to managing multiple packages from your local files system from within a singular top-level, root package.

This set of features makes up for a much more streamlined workflow handling linked packages from the local file system. Automating the linking process as part of `npm install` and avoiding manually having to use `npm link` in order to add references to packages that should be symlinked into the current `node_modules` folder.

We also refer to these packages being auto-symlinked during `npm install` as a single workspace, meaning it’s a nested package within the current local file system that is explicitly defined in the `package.json` `workspaces` configuration.

### Installing workspaces

Workspaces are usually defined via the `workspaces` property of the `package.json` file, e.g:

    {
      "name": "my-workspaces-powered-project",
      "workspaces": [
        "workspace-a"
      ]
    }

Given the above `package.json` example living at a current working directory `.` that contains a folder named `workspace-a` that disposes of a `package.json` inside it, defining a nodejs package, e.g:

    .
    +-- package.json
    `-- workspace-a
       `-- package.json

The expected result once running `npm install` in this current working directory `.` is that the folder `workspace-a` will get symlinked to the `node_modules` folder of the current working dir.

Below is a post `npm install` example, given that same previous example structure of files and folders:

    .
    +-- node_modules
    |  `-- workspace-a -> ../workspace-a
    +-- package-lock.json
    +-- package.json
    `-- workspace-a
       `-- package.json

### Using workspaces

Given the specifities of how Node.js handles module resolution it’s possible to consume any defined workspace by it’s declared `package.json` `name`. Continuing from the example defined above, let’s also create a Node.js script that will require the `workspace-a` example module, e.g:

    // ./workspace-a/index.js
    module.exports = 'a'

    // ./lib/index.js
    const moduleA = require('workspace-a')
    console.log(moduleA) // -> a

When running it with:

`node lib/index.js`

This demonstrates how the nature of `node_modules` resolution allows for workspaces to enable a portable workflow for requiring each workspace in such a way that is also easy to publish these nested workspaces to be consumed elsewhere.

### See also

- npm install
- npm publish