Skip to content

Commit

Permalink
docs(workspaces): update using npm section
Browse files Browse the repository at this point in the history
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
  • Loading branch information
ruyadorno authored and wraithgar committed Jun 10, 2021
1 parent ef668ab commit 8442295
Showing 1 changed file with 45 additions and 1 deletion.
46 changes: 45 additions & 1 deletion docs/content/using-npm/workspaces.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ single **workspace**, meaning it's a nested package within the current local
file system that is explicitly defined in the [`package.json`](/configuring-npm/package-json#workspaces)
`workspaces` configuration.

### Installing workspaces
### Defining workspaces

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

### Getting started with workspaces

You may automate the required steps to define a new workspace using
[npm init](/commands/npm-init). For example in a project that already has a
`package.json` defined you can run:

```
npm init -w ./packages/a
```

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`.

### Adding dependencies to a workspace

It's possible to directly add/remove/update dependencies of your workspaces
using the [`workspace` config](/using-npm/config#workspace).

For example, assuming the following structure:

```
.
+-- package.json
`-- packages
+-- a
| `-- package.json
`-- b
`-- package.json
```

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:

```
npm install abbrev -w a
```

Note: other installing commands such as `uninstall`, `ci`, etc will also
respect the provided `workspace` configuration.

### Using workspaces

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

0 comments on commit 8442295

Please sign in to comment.