1WORKSPACES(7) WORKSPACES(7)
2
6 workspaces - Working with workspaces
7 Description
9 Workspaces is a generic term that refers to the set of features in the
10 npm cli that provides support to managing multiple packages from your
11 local file system from within a singular top-level, root package.
12 This set of features makes up for a much more streamlined workflow han‐
14 dling linked packages from the local file system. Automating the link‐
15 ing process as part of npm install and avoiding manually having to use
16 npm link in order to add references to packages that should be sym‐
17 linked into the current node_modules folder.
18 We also refer to these packages being auto-symlinked during npm install
20 as a single workspace, meaning it's a nested package within the current
21 local file system that is explicitly defined in the package.json ⟨/con‐
22 figuring-npm/package-json#workspaces⟩ workspaces configuration.
23 Defining workspaces
25 Workspaces are usually defined via the workspaces property of the pack‐
26 age.json ⟨/configuring-npm/package-json#workspaces⟩ file, e.g:
27 {
29 "name": "my-workspaces-powered-project",
30 "workspaces": [
31 "packages/a"
32 ]
33 }
34 Given the above package.json example living at a current working direc‐
36 tory . that contains a folder named packages/a that itself contains a
37 package.json inside it, defining a Node.js package, e.g:
38 +-- package.json
40 `-- packages
41 +-- a
42 | `-- package.json
43 The expected result once running npm install in this current working
45 directory . is that the folder packages/a will get symlinked to the
46 node_modules folder of the current working dir.
47 Below is a post npm install example, given that same previous example
49 structure of files and folders:
50 +-- node_modules
52 | `-- a -> ../packages/a
53 +-- package-lock.json
54 +-- package.json
55 `-- packages
56 +-- a
57 | `-- package.json
58 Getting started with workspaces
60 You may automate the required steps to define a new workspace using npm
61 help init. For example in a project that already has a package.json de‐
62 fined you can run:
63 npm init -w ./packages/a
65 This command will create the missing folders and a new package.json
67 file (if needed) while also making sure to properly configure the
68 "workspaces" property of your root project package.json.
69 Adding dependencies to a workspace
71 It's possible to directly add/remove/update dependencies of your
72 workspaces using the workspace config ⟨/using-npm/config#workspace⟩.
73 For example, assuming the following structure:
75 +-- package.json
77 `-- packages
78 +-- a
79 | `-- package.json
80 `-- b
81 `-- package.json
82 If you want to add a dependency named abbrev from the registry as a de‐
84 pendency of your workspace a, you may use the workspace config to tell
85 the npm installer that package should be added as a dependency of the
86 provided workspace:
87 npm install abbrev -w a
89 Note: other installing commands such as uninstall, ci, etc will also
91 respect the provided workspace configuration.
92 Using workspaces
94 Given the specifities of how Node.js handles module resolution
95 ⟨https://nodejs.org/dist/latest-v14.x/docs/api/modules.html#mod‐
96 ules_all_together⟩ it's possible to consume any defined workspace by
97 its declared package.json name. Continuing from the example defined
98 above, let's also create a Node.js script that will require the
99 workspace a example module, e.g:
100 // ./packages/a/index.js
102 module.exports = 'a'
103 // ./lib/index.js
105 const moduleA = require('a')
106 console.log(moduleA) // -> a
107 When running it with:
109 node lib/index.js
111 This demonstrates how the nature of node_modules resolution allows for
113 workspaces to enable a portable workflow for requiring each workspace
114 in such a way that is also easy to npm help publish these nested
115 workspaces to be consumed elsewhere.
116 Running commands in the context of workspaces
118 You can use the workspace configuration option to run commands in the
119 context of a configured workspace. Additionally, if your current direc‐
120 tory is in a workspace, the workspace configuration is implicitly set,
121 and prefix is set to the root workspace.
122 Following is a quick example on how to use the npm run command in the
124 context of nested workspaces. For a project containing multiple
125 workspaces, e.g:
126 +-- package.json
128 `-- packages
129 +-- a
130 | `-- package.json
131 `-- b
132 `-- package.json
133 By running a command using the workspace option, it's possible to run
135 the given command in the context of that specific workspace. e.g:
136 npm run test --workspace=a
138 You could also run the command within the workspace.
140 cd packages/a && npm run test
142 Either will run the test script defined within the ./packages/a/pack‐
144 age.json file.
145 Please note that you can also specify this argument multiple times in
147 the command-line in order to target multiple workspaces, e.g:
148 npm run test --workspace=a --workspace=b
150 Or run the command for each workspace within the 'packages' folder:
152 npm run test --workspace=packages
154 It's also possible to use the workspaces (plural) configuration option
156 to enable the same behavior but running that command in the context of
157 all configured workspaces. e.g:
158 npm run test --workspaces
160 Will run the test script in both ./packages/a and ./packages/b.
162 Commands will be run in each workspace in the order they appear in your
164 package.json
165 {
167 "workspaces": [ "packages/a", "packages/b" ]
168 }
169 Order of run is different with:
171 {
173 "workspaces": [ "packages/b", "packages/a" ]
174 }
175 Ignoring missing scripts
177 It is not required for all of the workspaces to implement scripts run
178 with the npm run command.
179 By running the command with the --if-present flag, npm will ignore
181 workspaces missing target script.
182 npm run test --workspaces --if-present
184 See also
186 • npm help install
187 • npm help publish
189 • npm help run-script
191 • npm help config
193 November 2023 WORKSPACES(7)