|
| 1 | +--- |
| 2 | +section: using-npm |
| 3 | +title: workspaces |
| 4 | +description: Working with workspaces |
| 5 | +--- |
| 6 | +# scope(7) |
| 7 | + |
| 8 | +## Workspaces |
| 9 | + |
| 10 | +### Description |
| 11 | + |
| 12 | +**Workspaces** is a generic term that refers to the set of features in the |
| 13 | +npm cli that provides support to managing multiple packages from your local |
| 14 | +files system from within a singular top-level, root package. |
| 15 | + |
| 16 | +This set of features makes up for a much more streamlined workflow handling |
| 17 | +linked packages from the local file system. Automating the linking process |
| 18 | +as part of `npm install` and avoiding manually having to use `npm link` in |
| 19 | +order to add references to packages that should be symlinked into the current |
| 20 | +`node_modules` folder. |
| 21 | + |
| 22 | +We also refer to these packages being auto-symlinked during `npm install` as a |
| 23 | +single **workspace**, meaning it's a nested package within the current local |
| 24 | +file system that is explicitly defined in the [`package.json`](/using-npm/package-json) |
| 25 | +`workspaces` configuration. |
| 26 | + |
| 27 | +### Installing workspaces |
| 28 | + |
| 29 | +Workspaces are usually defined via the `workspaces` property of the |
| 30 | +[`package.json`](/using-npm/package-json) file, e.g: |
| 31 | + |
| 32 | +```json |
| 33 | +{ |
| 34 | + "name": "my-workspaces-powered-project", |
| 35 | + "workspaces": [ |
| 36 | + "workspace-a" |
| 37 | + ] |
| 38 | +} |
| 39 | +``` |
| 40 | + |
| 41 | +Given the above `package.json` example living at a current working |
| 42 | +directory `.` that contains a folder named `workspace-a` that disposes |
| 43 | +of a `package.json` inside it, defining a nodejs package, e.g: |
| 44 | + |
| 45 | +``` |
| 46 | +. |
| 47 | ++-- package.json |
| 48 | +`-- workspace-a |
| 49 | + `-- package.json |
| 50 | +``` |
| 51 | + |
| 52 | +The expected result once running `npm install` in this current working |
| 53 | +directory `.` is that the folder `workspace-a` will get symlinked to the |
| 54 | +`node_modules` folder of the current working dir. |
| 55 | + |
| 56 | +Below is a post `npm install` example, given that same previous example |
| 57 | +structure of files and folders: |
| 58 | + |
| 59 | +``` |
| 60 | +. |
| 61 | ++-- node_modules |
| 62 | +| `-- workspace-a -> ../workspace-a |
| 63 | ++-- package-lock.json |
| 64 | ++-- package.json |
| 65 | +`-- workspace-a |
| 66 | + `-- package.json |
| 67 | +``` |
| 68 | + |
| 69 | +### Using workspaces |
| 70 | + |
| 71 | +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 |
| 72 | +by it's declared `package.json` `name`. Continuing from the example defined |
| 73 | +above, let's also create a Node.js script that will require the `workspace-a` |
| 74 | +example module, e.g: |
| 75 | + |
| 76 | +``` |
| 77 | +// ./workspace-a/index.js |
| 78 | +module.exports = 'a' |
| 79 | +
|
| 80 | +// ./lib/index.js |
| 81 | +const moduleA = require('workspace-a') |
| 82 | +console.log(moduleA) // -> a |
| 83 | +``` |
| 84 | + |
| 85 | +When running it with: |
| 86 | + |
| 87 | +`node lib/index.js` |
| 88 | + |
| 89 | +This demonstrates how the nature of `node_modules` resolution allows for |
| 90 | +**workspaces** to enable a portable workflow for requiring each **workspace** |
| 91 | +in such a way that is also easy to [publish](/cli-commands/publish) these |
| 92 | +nested workspaces to be consumed elsewhere. |
| 93 | + |
| 94 | +### See also |
| 95 | + |
| 96 | +* [npm install](/cli-commands/install) |
| 97 | +* [npm publish](/cli-commands/publish) |
| 98 | + |
0 commit comments