@cryptotaxi247 / documentation-1
Code Commits Issues Pulls Sessions CI/CD
kartykp/gat-bypass-2fa-docs
@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 178 lines 5.9 KB
Raw
1 ---
2 title: workspaces
3 section: 7
4 description: Working with workspaces
5 github_repo: npm/cli
6 github_branch: release/v7
7 github_path: docs/content/using-npm/workspaces.md
8 redirect_from:
9 - /cli-documentation/v7/misc/workspaces
10 - /cli-documentation/v7/using-npm/workspaces
11 - /cli/v7/misc/workspaces
12 ---
13
14 ### Description
15
16 **Workspaces** is a generic term that refers to the set of features in the npm cli that provides support to managing multiple packages from your local files system from within a singular top-level, root package.
17
18 This set of features makes up for a much more streamlined workflow handling linked packages from the local file system. Automating the linking process as part of `npm install` and avoiding manually having to use `npm link` in order to add references to packages that should be symlinked into the current `node_modules` folder.
19
20 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/v7/configuring-npm/package-json#workspaces) `workspaces` configuration.
21
22 ### Defining workspaces
23
24 Workspaces are usually defined via the `workspaces` property of the [`package.json`](/cli/v7/configuring-npm/package-json#workspaces) file, e.g:
25
26 ```json
27 {
28 "name": "my-workspaces-powered-project",
29 "workspaces": ["workspace-a"]
30 }
31 ```
32
33 Given the above `package.json` example living at a current working directory `.` that contains a folder named `workspace-a` that itself contains a `package.json` inside it, defining a Node.js package, e.g:
34
35 ```
36 .
37 +-- package.json
38 `-- workspace-a
39 `-- package.json
40 ```
41
42 The expected result once running `npm install` in this current working directory `.` is that the folder `workspace-a` will get symlinked to the `node_modules` folder of the current working dir.
43
44 Below is a post `npm install` example, given that same previous example structure of files and folders:
45
46 ```
47 .
48 +-- node_modules
49 | `-- workspace-a -> ../workspace-a
50 +-- package-lock.json
51 +-- package.json
52 `-- workspace-a
53 `-- package.json
54 ```
55
56 ### Getting started with workspaces
57
58 You may automate the required steps to define a new workspace using [npm init](/cli/v7/commands/npm-init). For example in a project that already has a `package.json` defined you can run:
59
60 ```
61 npm init -w ./packages/a
62 ```
63
64 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`.
65
66 ### Adding dependencies to a workspace
67
68 It's possible to directly add/remove/update dependencies of your workspaces using the [`workspace` config](/cli/v7/using-npm/config#workspace).
69
70 For example, assuming the following structure:
71
72 ```
73 .
74 +-- package.json
75 `-- packages
76 +-- a
77 | `-- package.json
78 `-- b
79 `-- package.json
80 ```
81
82 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:
83
84 ```
85 npm install abbrev -w a
86 ```
87
88 Note: other installing commands such as `uninstall`, `ci`, etc will also respect the provided `workspace` configuration.
89
90 ### Using workspaces
91
92 Given the [specifities 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 it's 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:
93
94 ```
95 // ./workspace-a/index.js
96 module.exports = 'a'
97
98 // ./lib/index.js
99 const moduleA = require('workspace-a')
100 console.log(moduleA) // -> a
101 ```
102
103 When running it with:
104
105 `node lib/index.js`
106
107 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/v7/commands/npm-publish) these nested workspaces to be consumed elsewhere.
108
109 ### Running commands in the context of workspaces
110
111 You can use the `workspace` configuration option to run commands in the context of a configured workspace.
112
113 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:
114
115 ```
116 .
117 +-- package.json
118 `-- packages
119 +-- a
120 | `-- package.json
121 `-- b
122 `-- package.json
123 ```
124
125 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:
126
127 ```
128 npm run test --workspace=a
129 ```
130
131 This will run the `test` script defined within the `./packages/a/package.json` file.
132
133 Please note that you can also specify this argument multiple times in the command-line in order to target multiple workspaces, e.g:
134
135 ```
136 npm run test --workspace=a --workspace=b
137 ```
138
139 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:
140
141 ```
142 npm run test --workspaces
143 ```
144
145 Will run the `test` script in both `./packages/a` and `./packages/b`.
146
147 Commands will be run in each workspace in the order they appear in your `package.json`
148
149 ```
150 {
151 "workspaces": [ "packages/a", "packages/b" ]
152 }
153 ```
154
155 Order of run is different with:
156
157 ```
158 {
159 "workspaces": [ "packages/b", "packages/a" ]
160 }
161 ```
162
163 ### Ignoring missing scripts
164
165 It is not required for all of the workspaces to implement scripts run with the `npm run` command.
166
167 By running the command with the `--if-present` flag, npm will ignore workspaces missing target script.
168
169 ```
170 npm run test --workspaces --if-present
171 ```
172
173 ### See also
174
175 - [npm install](/cli/v7/commands/npm-install)
176 - [npm publish](/cli/v7/commands/npm-publish)
177 - [npm run-script](/cli/v7/commands/npm-run-script)
178 - [config](/cli/v7/using-npm/config)