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 npm help pack‐
22 age.json workspaces configuration.
23 Defining workspaces
25 Workspaces are usually defined via the workspaces property of the npm
26 help package.json 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 .
40 +-- package.json
41 `-- packages
42 +-- a
43 | `-- package.json
44 The expected result once running npm install in this current working
46 directory . is that the folder packages/a will get symlinked to the
47 node_modules folder of the current working dir.
48 Below is a post npm install example, given that same previous example
50 structure of files and folders:
51 .
53 +-- node_modules
54 | `-- a -> ../packages/a
55 +-- package-lock.json
56 +-- package.json
57 `-- packages
58 +-- a
59 | `-- package.json
60 Getting started with workspaces
62 You may automate the required steps to define a new workspace using npm
63 help init. For example in a project that already has a package.json de‐
64 fined you can run:
65 npm init -w ./packages/a
67 This command will create the missing folders and a new package.json
69 file (if needed) while also making sure to properly configure the
70 "workspaces" property of your root project package.json.
71 Adding dependencies to a workspace
73 It's possible to directly add/remove/update dependencies of your
74 workspaces using the npm help workspace config.
75 For example, assuming the following structure:
77 .
79 +-- package.json
80 `-- packages
81 +-- a
82 | `-- package.json
83 `-- b
84 `-- package.json
85 If you want to add a dependency named abbrev from the registry as a de‐
87 pendency of your workspace a, you may use the workspace config to tell
88 the npm installer that package should be added as a dependency of the
89 provided workspace:
90 npm install abbrev -w a
92 Note: other installing commands such as uninstall, ci, etc will also
94 respect the provided workspace configuration.
95 Using workspaces
97 Given the specifities of how Node.js handles module resolution
98 https://nodejs.org/dist/latest-v14.x/docs/api/modules.html#mod‐
99 ules_all_together it's possible to consume any defined workspace by its
100 declared package.json name. Continuing from the example defined above,
101 let's also create a Node.js script that will require the workspace a
102 example module, e.g:
103 // ./packages/a/index.js
105 module.exports = 'a'
106 // ./lib/index.js
108 const moduleA = require('a')
109 console.log(moduleA) // -> a
110 When running it with:
112 node lib/index.js
114 This demonstrates how the nature of node_modules resolution allows for
116 workspaces to enable a portable workflow for requiring each workspace
117 in such a way that is also easy to npm help publish these nested
118 workspaces to be consumed elsewhere.
119 Running commands in the context of workspaces
121 You can use the workspace configuration option to run commands in the
122 context of a configured workspace. Additionally, if your current di‐
123 rectory is in a workspace, the workspace configuration is implicitly
124 set, and prefix is set to the root workspace.
125 Following is a quick example on how to use the npm run command in the
127 context of nested workspaces. For a project containing multiple
128 workspaces, e.g:
129 .
131 +-- package.json
132 `-- packages
133 +-- a
134 | `-- package.json
135 `-- b
136 `-- package.json
137 By running a command using the workspace option, it's possible to run
139 the given command in the context of that specific workspace. e.g:
140 npm run test --workspace=a
142 You could also run the command within the workspace.
144 cd packages/a && npm run test
146 Either will run the test script defined within the ./packages/a/pack‐
148 age.json file.
149 Please note that you can also specify this argument multiple times in
151 the command-line in order to target multiple workspaces, e.g:
152 npm run test --workspace=a --workspace=b
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 September 2022 WORKSPACES(7)