@cryptotaxi247 / documentation
Code Commits Issues Pulls Sessions CI/CD
maitxn/version-bump-tar
@reggi/path-to-regexp dependabot/npm_and_yarn/main/copy-to-clipboard-4.0.2 dependabot/npm_and_yarn/main/eslint-10.4.0 dependabot/npm_and_yarn/main/npmcli/eslint-config-7.0.0 dependabot/npm_and_yarn/main/proc-log-7.0.0 dependabot/npm_and_yarn/npm_and_yarn-826852524d dependabot/npm_and_yarn/npm_and_yarn-ab9a7f4bc2 deprecate-totp-2fa dhei/classic-tokens gat-bypass-2fa-docs jpg619/fix-accessibility-content-flow jpg619/version-bump-tar-2 kartykp/gat-bypass-2fa-docs kartykp/upgrade-path-to-regex main maitxn/version-bump-tar patch-1 reggi/cache-based-on-version reggi/dev-engines reggi/fix-transform-prettier reggi/overrides update-search-sensitivity
mdx 218 lines 6.99 KB
Raw
1 ---
2 title: Workspaces
3 section: 7
4 description: Working with workspaces
5 github_repo: npm/cli
6 github_branch: latest
7 github_path: docs/lib/content/using-npm/workspaces.md
8 redirect_from:
9 - /cli-documentation/misc/workspaces
10 - /cli-documentation/using-npm/workspaces
11 - /cli-documentation/v11/misc/workspaces
12 - /cli-documentation/v11/using-npm/workspaces
13 - /cli/misc/workspaces
14 - /cli/using-npm/workspaces
15 - /cli/v11/misc/workspaces
16 - /misc/workspaces
17 - /using-npm/workspaces
18 ---
19
20 ### Description
21
22 **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.
23
24 This set of features makes up for a much more streamlined workflow handling linked packages from the local file system. It 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.
25
26 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`](/cli/v11/configuring-npm/package-json#workspaces) `workspaces` configuration.
27
28 ### Defining workspaces
29
30 Workspaces are usually defined via the `workspaces` property of the [`package.json`](/cli/v11/configuring-npm/package-json#workspaces) file, e.g:
31
32 ```json
33 {
34 "name": "my-workspaces-powered-project",
35 "workspaces": ["packages/a"]
36 }
37 ```
38
39 Given 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:
40
41 ```
42 .
43 +-- package.json
44 `-- packages
45 +-- a
46 | `-- package.json
47 ```
48
49 The 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.
50
51 Below is a post `npm install` example, given that same previous example structure of files and folders:
52
53 ```
54 .
55 +-- node_modules
56 | `-- a -> ../packages/a
57 +-- package-lock.json
58 +-- package.json
59 `-- packages
60 +-- a
61 | `-- package.json
62 ```
63
64 ### Getting started with workspaces
65
66 You may automate the required steps to define a new workspace using [npm init](/cli/v11/commands/npm-init). For example in a project that already has a `package.json` defined you can run:
67
68 ```
69 npm init -w ./packages/a
70 ```
71
72 This command will create the missing folders and a new `package.json` file (if needed) while also making sure to properly configure the `"workspaces"` property of your root project `package.json`.
73
74 ### Adding dependencies to a workspace
75
76 It's possible to directly add/remove/update dependencies of your workspaces using the [`workspace` config](/cli/v11/using-npm/config#workspace).
77
78 For example, assuming the following structure:
79
80 ```
81 .
82 +-- package.json
83 `-- packages
84 +-- a
85 | `-- package.json
86 `-- b
87 `-- package.json
88 ```
89
90 If 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:
91
92 ```
93 npm install abbrev -w a
94 ```
95
96 **Adding a workspace as a dependency of another workspace:**
97
98 If you want to add workspace **b** as a dependency of workspace **a**, you can use the workspace protocol in the dependency specifier:
99
100 ```
101 npm install b@workspace:* -w a
102 ```
103
104 This will add an entry to workspace **a**'s `package.json` like:
105
106 ```json
107 {
108 "dependencies": {
109 "b": "workspace:*"
110 }
111 }
112 ```
113
114 The `workspace:` protocol tells npm to link to the local workspace rather than fetching from the registry. The `*` version means it will use whatever version is defined in workspace **b**'s `package.json`.
115
116 Note: other installing commands such as `uninstall`, `ci`, etc will also respect the provided `workspace` configuration.
117
118 ### Using workspaces
119
120 Given 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`. Continuing from the example defined above, let's also create a Node.js script that will require the workspace `a` example module, e.g:
121
122 ```
123 // ./packages/a/index.js
124 module.exports = 'a'
125
126 // ./lib/index.js
127 const moduleA = require('a')
128 console.log(moduleA) // -> a
129 ```
130
131 When running it with:
132
133 `node lib/index.js`
134
135 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](/cli/v11/commands/npm-publish) these nested workspaces to be consumed elsewhere.
136
137 ### Running commands in the context of workspaces
138
139 You can use the `workspace` configuration option to run commands in the context of a configured workspace. Additionally, if your current directory is in a workspace, the `workspace` configuration is implicitly set, and `prefix` is set to the root workspace.
140
141 Following is a quick example on how to use the `npm run` command in the context of nested workspaces. For a project containing multiple workspaces, e.g:
142
143 ```
144 .
145 +-- package.json
146 `-- packages
147 +-- a
148 | `-- package.json
149 `-- b
150 `-- package.json
151 ```
152
153 By running a command using the `workspace` option, it's possible to run the given command in the context of that specific workspace. e.g:
154
155 ```
156 npm run test --workspace=a
157 ```
158
159 You could also run the command within the workspace.
160
161 ```
162 cd packages/a && npm run test
163 ```
164
165 Either will run the `test` script defined within the `./packages/a/package.json` file.
166
167 Please note that you can also specify this argument multiple times in the command-line in order to target multiple workspaces, e.g:
168
169 ```
170 npm run test --workspace=a --workspace=b
171 ```
172
173 Or run the command for each workspace within the 'packages' folder:
174
175 ```
176 npm run test --workspace=packages
177 ```
178
179 It'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. e.g:
180
181 ```
182 npm run test --workspaces
183 ```
184
185 Will run the `test` script in both `./packages/a` and `./packages/b`.
186
187 Commands 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
195 Order of run is different with:
196
197 ```
198 {
199 "workspaces": [ "packages/b", "packages/a" ]
200 }
201 ```
202
203 ### Ignoring missing scripts
204
205 It is not required for all of the workspaces to implement scripts run with the `npm run` command.
206
207 By running the command with the `--if-present` flag, npm will ignore workspaces missing target script.
208
209 ```
210 npm run test --workspaces --if-present
211 ```
212
213 ### See also
214
215 - [npm install](/cli/v11/commands/npm-install)
216 - [npm publish](/cli/v11/commands/npm-publish)
217 - [npm run](/cli/v11/commands/npm-run)
218 - [config](/cli/v11/using-npm/config)