nodejs/deps/npm/docs/content/using-npm/workspaces.md

---
title: workspaces
section: 7
description: Working with workspaces
---

### 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`](/using-npm/package-json)
`workspaces` configuration.

### Installing workspaces

Workspaces are usually defined via the `workspaces` property of the
[`package.json`](/using-npm/package-json) file, e.g:

```json
{
  "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](https://nodejs.org/dist/latest-v14.x/docs/api/modules.html#modules_all_together) 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](/commands/npm-publish) these
nested workspaces to be consumed elsewhere.

### See also

* [npm install](/commands/npm-install)
* [npm publish](/commands/npm-publish)