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 "workspace-a"
32 ]
33 }
34 Given the above package.json example living at a current working direc‐
36 tory . that contains a folder named workspace-a that itself contains a
37 package.json inside it, defining a Node.js package, e.g:
38 .
40 +-- package.json
41 `-- workspace-a
42 `-- package.json
43 The expected result once running npm install in this current working
45 directory . is that the folder workspace-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 .
52 +-- node_modules
53 | `-- workspace-a -> ../workspace-a
54 +-- package-lock.json
55 +-- package.json
56 `-- workspace-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 npm help workspace config.
73 For example, assuming the following structure:
75 .
77 +-- package.json
78 `-- packages
79 +-- a
80 | `-- package.json
81 `-- b
82 `-- package.json
83 If you want to add a dependency named abbrev from the registry as a de‐
85 pendency of your workspace a, you may use the workspace config to tell
86 the npm installer that package should be added as a dependency of the
87 provided workspace:
88 npm install abbrev -w a
90 Note: other installing commands such as uninstall, ci, etc will also
92 respect the provided workspace configuration.
93 Using workspaces
95 Given the specifities of how Node.js handles module resolution
96 https://nodejs.org/dist/latest-v14.x/docs/api/modules.html#mod‐
97 ules_all_together it's possible to consume any defined workspace by its
98 declared package.json name. Continuing from the example defined above,
99 let's also create a Node.js script that will require the workspace-a
100 example module, e.g:
101 // ./workspace-a/index.js
103 module.exports = 'a'
104 // ./lib/index.js
106 const moduleA = require('workspace-a')
107 console.log(moduleA) // -> a
108 When running it with:
110 node lib/index.js
112 This demonstrates how the nature of node_modules resolution allows for
114 workspaces to enable a portable workflow for requiring each workspace
115 in such a way that is also easy to npm help publish these nested
116 workspaces to be consumed elsewhere.
117 Running commands in the context of workspaces
119 You can use the workspace configuration option to run commands in the
120 context of a configured workspace.
121 Following is a quick example on how to use the npm run command in the
123 context of nested workspaces. For a project containing multiple
124 workspaces, e.g:
125 .
127 +-- 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 This will run the test script defined within the ./packages/a/pack‐
140 age.json file.
141 Please note that you can also specify this argument multiple times in
143 the command-line in order to target multiple workspaces, e.g:
144 npm run test --workspace=a --workspace=b
146 It's also possible to use the workspaces (plural) configuration option
148 to enable the same behavior but running that command in the context of
149 all configured workspaces. e.g:
150 npm run test --workspaces
152 Will run the test script in both ./packages/a and ./packages/b.
154 Commands will be run in each workspace in the order they appear in your
156 package.json
157 {
159 "workspaces": [ "packages/a", "packages/b" ]
160 }
161 Order of run is different with:
163 {
165 "workspaces": [ "packages/b", "packages/a" ]
166 }
167 Ignoring missing scripts
169 It is not required for all of the workspaces to implement scripts run
170 with the npm run command.
171 By running the command with the --if-present flag, npm will ignore
173 workspaces missing target script.
174 npm run test --workspaces --if-present
176 See also
178 • npm help install
179 • npm help publish
181 • npm help run-script
183 • npm help config
185 January 2022 WORKSPACES(7)