1---
2title: workspaces
3section: 7
4description: Working with workspaces
5---
6
7### Description
8
9**Workspaces** is a generic term that refers to the set of features in the
10npm cli that provides support for managing multiple packages from your local
11file system from within a singular top-level, root package.
12
13This set of features makes up for a much more streamlined workflow handling
14linked packages from the local file system. It automates the linking process
15as part of `npm install` and removes the need to manually use `npm link` in
16order to add references to packages that should be symlinked into the current
17`node_modules` folder.
18
19We also refer to these packages being auto-symlinked during `npm install` as a
20single **workspace**, meaning it's a nested package within the current local
21file system that is explicitly defined in the [`package.json`](/configuring-npm/package-json#workspaces)
22`workspaces` configuration.
23
24### Defining workspaces
25
26Workspaces are usually defined via the `workspaces` property of the
27[`package.json`](/configuring-npm/package-json#workspaces) file, e.g:
28
29```json
30{
31  "name": "my-workspaces-powered-project",
32  "workspaces": [
33    "packages/a"
34  ]
35}
36```
37
38Given the above `package.json` example living at a current working
39directory `.` that contains a folder named `packages/a` that itself contains
40a `package.json` inside it, defining a Node.js package, e.g:
41
42```
43.
44+-- package.json
45`-- packages
46   +-- a
47   |   `-- package.json
48```
49
50The expected result once running `npm install` in this current working
51directory `.` is that the folder `packages/a` will get symlinked to the
52`node_modules` folder of the current working dir.
53
54Below is a post `npm install` example, given that same previous example
55structure of files and folders:
56
57```
58.
59+-- node_modules
60|  `-- a -> ../packages/a
61+-- package-lock.json
62+-- package.json
63`-- packages
64   +-- a
65   |   `-- package.json
66```
67
68### Getting started with workspaces
69
70You may automate the required steps to define a new workspace using
71[npm init](/commands/npm-init). For example in a project that already has a
72`package.json` defined you can run:
73
74```
75npm init -w ./packages/a
76```
77
78This command will create the missing folders and a new `package.json`
79file (if needed) while also making sure to properly configure the
80`"workspaces"` property of your root project `package.json`.
81
82### Adding dependencies to a workspace
83
84It's possible to directly add/remove/update dependencies of your workspaces
85using the [`workspace` config](/using-npm/config#workspace).
86
87For example, assuming the following structure:
88
89```
90.
91+-- package.json
92`-- packages
93   +-- a
94   |   `-- package.json
95   `-- b
96       `-- package.json
97```
98
99If you want to add a dependency named `abbrev` from the registry as a
100dependency of your workspace **a**, you may use the workspace config to tell
101the npm installer that package should be added as a dependency of the provided
102workspace:
103
104```
105npm install abbrev -w a
106```
107
108Note: other installing commands such as `uninstall`, `ci`, etc will also
109respect the provided `workspace` configuration.
110
111### Using workspaces
112
113Given the [specifics 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
114by its declared `package.json` `name`. Continuing from the example defined
115above, let's also create a Node.js script that will require the workspace `a`
116example module, e.g:
117
118```
119// ./packages/a/index.js
120module.exports = 'a'
121
122// ./lib/index.js
123const moduleA = require('a')
124console.log(moduleA) // -> a
125```
126
127When running it with:
128
129`node lib/index.js`
130
131This demonstrates how the nature of `node_modules` resolution allows for
132**workspaces** to enable a portable workflow for requiring each **workspace**
133in such a way that is also easy to [publish](/commands/npm-publish) these
134nested workspaces to be consumed elsewhere.
135
136### Running commands in the context of workspaces
137
138You can use the `workspace` configuration option to run commands in the context
139of a configured workspace.
140Additionally, if your current directory is in a workspace, the `workspace`
141configuration is implicitly set, and `prefix` is set to the root workspace.
142
143Following is a quick example on how to use the `npm run` command in the context
144of nested workspaces. For a project containing multiple workspaces, e.g:
145
146```
147.
148+-- package.json
149`-- packages
150   +-- a
151   |   `-- package.json
152   `-- b
153       `-- package.json
154```
155
156By running a command using the `workspace` option, it's possible to run the
157given command in the context of that specific workspace. e.g:
158
159```
160npm run test --workspace=a
161```
162
163You could also run the command within the workspace.
164
165```
166cd packages/a && npm run test
167```
168
169Either will run the `test` script defined within the
170`./packages/a/package.json` file.
171
172Please note that you can also specify this argument multiple times in the
173command-line in order to target multiple workspaces, e.g:
174
175```
176npm run test --workspace=a --workspace=b
177```
178
179Or run the command for each workspace within the 'packages' folder:
180```
181npm run test --workspace=packages
182```
183
184It's also possible to use the `workspaces` (plural) configuration option to
185enable the same behavior but running that command in the context of **all**
186configured workspaces. e.g:
187
188```
189npm run test --workspaces
190```
191
192Will run the `test` script in both `./packages/a` and `./packages/b`.
193
194Commands will be run in each workspace in the order they appear in your `package.json`
195
196```
197{
198  "workspaces": [ "packages/a", "packages/b" ]
199}
200```
201
202Order of run is different with:
203
204```
205{
206  "workspaces": [ "packages/b", "packages/a" ]
207}
208```
209
210### Ignoring missing scripts
211
212It is not required for all of the workspaces to implement scripts run with the `npm run` command.
213
214By running the command with the `--if-present` flag, npm will ignore workspaces missing target script.
215
216```
217npm run test --workspaces --if-present
218```
219
220### See also
221
222* [npm install](/commands/npm-install)
223* [npm publish](/commands/npm-publish)
224* [npm run-script](/commands/npm-run-script)
225* [config](/using-npm/config)
226
227