codekingpro/portable-devtools

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