Skip to content

Commit 8442295

Browse files
ruyadornowraithgar
authored andcommitted
docs(workspaces): update using npm section
Added examples of using `npm init` to bootstrap a new workspace and a section on how to add/manage dependencies to workspaces. PR-URL: #3392 Credit: @ruyadorno Close: #3392 Reviewed-by: @wraithgar
1 parent ef668ab commit 8442295

File tree

1 file changed

+45
-1
lines changed

1 file changed

+45
-1
lines changed

docs/content/using-npm/workspaces.md

+45-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ single **workspace**, meaning it's a nested package within the current local
2121
file system that is explicitly defined in the [`package.json`](/configuring-npm/package-json#workspaces)
2222
`workspaces` configuration.
2323

24-
### Installing workspaces
24+
### Defining workspaces
2525

2626
Workspaces are usually defined via the `workspaces` property of the
2727
[`package.json`](/configuring-npm/package-json#workspaces) file, e.g:
@@ -63,6 +63,49 @@ structure of files and folders:
6363
`-- package.json
6464
```
6565

66+
### Getting started with workspaces
67+
68+
You may automate the required steps to define a new workspace using
69+
[npm init](/commands/npm-init). For example in a project that already has a
70+
`package.json` defined you can run:
71+
72+
```
73+
npm init -w ./packages/a
74+
```
75+
76+
This command will create the missing folders and a new `package.json`
77+
file (if needed) while also making sure to properly configure the
78+
`"workspaces"` property of your root project `package.json`.
79+
80+
### Adding dependencies to a workspace
81+
82+
It's possible to directly add/remove/update dependencies of your workspaces
83+
using the [`workspace` config](/using-npm/config#workspace).
84+
85+
For example, assuming the following structure:
86+
87+
```
88+
.
89+
+-- package.json
90+
`-- packages
91+
+-- a
92+
| `-- package.json
93+
`-- b
94+
`-- package.json
95+
```
96+
97+
If you want to add a dependency named `abbrev` from the registry as a
98+
dependency of your workspace **a**, you may use the workspace config to tell
99+
the npm installer that package should be added as a dependency of the provided
100+
workspace:
101+
102+
```
103+
npm install abbrev -w a
104+
```
105+
106+
Note: other installing commands such as `uninstall`, `ci`, etc will also
107+
respect the provided `workspace` configuration.
108+
66109
### Using workspaces
67110

68111
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
@@ -138,4 +181,5 @@ Will run the `test` script in both `./packages/a` and `./packages/b`.
138181
* [npm install](/commands/npm-install)
139182
* [npm publish](/commands/npm-publish)
140183
* [npm run-script](/commands/npm-run-script)
184+
* [config](/using-npm/config)
141185

0 commit comments

Comments
 (0)