mirror of
https://github.com/nodejs/node.git
synced 2025-05-13 13:01:31 +00:00
78237591f8
PR-URL: https://github.com/nodejs/node/pull/37968 Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
142 lines
3.9 KiB
Markdown
142 lines
3.9 KiB
Markdown
---
|
|
title: workspaces
|
|
section: 7
|
|
description: Working with workspaces
|
|
---
|
|
|
|
### Description
|
|
|
|
**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.
|
|
|
|
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.
|
|
|
|
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`](/configuring-npm/package-json#workspaces)
|
|
`workspaces` configuration.
|
|
|
|
### Installing workspaces
|
|
|
|
Workspaces are usually defined via the `workspaces` property of the
|
|
[`package.json`](/configuring-npm/package-json#workspaces) file, e.g:
|
|
|
|
```json
|
|
{
|
|
"name": "my-workspaces-powered-project",
|
|
"workspaces": [
|
|
"workspace-a"
|
|
]
|
|
}
|
|
```
|
|
|
|
Given the above `package.json` example living at a current working
|
|
directory `.` that contains a folder named `workspace-a` that disposes
|
|
of a `package.json` inside it, defining a nodejs package, e.g:
|
|
|
|
```
|
|
.
|
|
+-- package.json
|
|
`-- workspace-a
|
|
`-- package.json
|
|
```
|
|
|
|
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.
|
|
|
|
Below is a post `npm install` example, given that same previous example
|
|
structure of files and folders:
|
|
|
|
```
|
|
.
|
|
+-- node_modules
|
|
| `-- workspace-a -> ../workspace-a
|
|
+-- package-lock.json
|
|
+-- package.json
|
|
`-- workspace-a
|
|
`-- package.json
|
|
```
|
|
|
|
### 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
|
|
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:
|
|
|
|
```
|
|
// ./workspace-a/index.js
|
|
module.exports = 'a'
|
|
|
|
// ./lib/index.js
|
|
const moduleA = require('workspace-a')
|
|
console.log(moduleA) // -> a
|
|
```
|
|
|
|
When running it with:
|
|
|
|
`node lib/index.js`
|
|
|
|
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](/commands/npm-publish) these
|
|
nested workspaces to be consumed elsewhere.
|
|
|
|
### Running commands in the context of workspaces
|
|
|
|
You can use the `workspace` configuration option to run commands in the context
|
|
of a configured workspace.
|
|
|
|
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:
|
|
|
|
```
|
|
.
|
|
+-- package.json
|
|
`-- packages
|
|
+-- a
|
|
| `-- package.json
|
|
`-- b
|
|
`-- package.json
|
|
```
|
|
|
|
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:
|
|
|
|
```
|
|
npm run test --workspace=a
|
|
```
|
|
|
|
This will run the `test` script defined within the
|
|
`./packages/a/package.json` file.
|
|
|
|
Please note that you can also specify this argument multiple times in the
|
|
command-line in order to target multiple workspaces, e.g:
|
|
|
|
```
|
|
npm run test --workspace=a --workspace=b
|
|
```
|
|
|
|
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:
|
|
|
|
```
|
|
npm run test --workspaces
|
|
```
|
|
|
|
Will run the `test` script in both `./packages/a` and `./packages/b`.
|
|
|
|
### See also
|
|
|
|
* [npm install](/commands/npm-install)
|
|
* [npm publish](/commands/npm-publish)
|
|
* [npm run-script](/commands/npm-run-script)
|
|
|