File Explorer

1.TH "WORKSPACES" "7" "February 2026" "NPM@11.11.0" ""2.SH "NAME"3\fBWorkspaces\fR - Working with workspaces4.SS "Description"5.P6\fBWorkspaces\fR is a generic term that refers to the set of features in the npm cli that provides support for managing multiple packages from your local file system from within a singular top-level, root package.7.P8This set of features makes up for a much more streamlined workflow handling linked packages from the local file system. It automates the linking process as part of \fBnpm install\fR and removes the need to manually use \fBnpm link\fR in order to add references to packages that should be symlinked into the current \fBnode_modules\fR folder.9.P10We also refer to these packages being auto-symlinked during \fBnpm install\fR as a single \fBworkspace\fR, meaning it's a nested package within the current local file system that is explicitly defined in the \fB\[rs]fBpackage.json\[rs]fR\fR \fI\(la/configuring-npm/package-json#workspaces\(ra\fR \fBworkspaces\fR configuration.11.SS "Defining workspaces"12.P13Workspaces are usually defined via the \fBworkspaces\fR property of the \fB\[rs]fBpackage.json\[rs]fR\fR \fI\(la/configuring-npm/package-json#workspaces\(ra\fR file, e.g:14.P15.RS 216.nf17{18  "name": "my-workspaces-powered-project",19  "workspaces": \[lB]20    "packages/a"21  \[rB]22}23.fi24.RE25.P26Given the above \fBpackage.json\fR example living at a current working directory \fB.\fR that contains a folder named \fBpackages/a\fR that itself contains a \fBpackage.json\fR inside it, defining a Node.js package, e.g:27.P28.RS 229.nf30.31+-- package.json32`-- packages33   +-- a34   |   `-- package.json35.fi36.RE37.P38The expected result once running \fBnpm install\fR in this current working directory \fB.\fR is that the folder \fBpackages/a\fR will get symlinked to the \fBnode_modules\fR folder of the current working dir.39.P40Below is a post \fBnpm install\fR example, given that same previous example structure of files and folders:41.P42.RS 243.nf44.45+-- node_modules46|  `-- a -> ../packages/a47+-- package-lock.json48+-- package.json49`-- packages50   +-- a51   |   `-- package.json52.fi53.RE54.SS "Getting started with workspaces"55.P56You may automate the required steps to define a new workspace using npm help init. For example in a project that already has a \fBpackage.json\fR defined you can run:57.P58.RS 259.nf60npm init -w ./packages/a61.fi62.RE63.P64This command will create the missing folders and a new \fBpackage.json\fR file (if needed) while also making sure to properly configure the \fB"workspaces"\fR property of your root project \fBpackage.json\fR.65.SS "Adding dependencies to a workspace"66.P67It's possible to directly add/remove/update dependencies of your workspaces using the \fB\[rs]fBworkspace\[rs]fR config\fR \fI\(la/using-npm/config#workspace\(ra\fR.68.P69For example, assuming the following structure:70.P71.RS 272.nf73.74+-- package.json75`-- packages76   +-- a77   |   `-- package.json78   `-- b79       `-- package.json80.fi81.RE82.P83If you want to add a dependency named \fBabbrev\fR from the registry as a dependency of your workspace \fBa\fR, you may use the workspace config to tell the npm installer that package should be added as a dependency of the provided workspace:84.P85.RS 286.nf87npm install abbrev -w a88.fi89.RE90.P91\fBAdding a workspace as a dependency of another workspace:\fR92.P93If you want to add workspace \fBb\fR as a dependency of workspace \fBa\fR, you can use the workspace protocol in the dependency specifier:94.P95.RS 296.nf97npm install b@workspace:* -w a98.fi99.RE100.P101This will add an entry to workspace \fBa\fR's \fBpackage.json\fR like:102.P103.RS 2104.nf105{106  "dependencies": {107    "b": "workspace:*"108  }109}110.fi111.RE112.P113The \fBworkspace:\fR protocol tells npm to link to the local workspace rather than fetching from the registry. The \fB*\fR version means it will use whatever version is defined in workspace \fBb\fR's \fBpackage.json\fR.114.P115Note: other installing commands such as \fBuninstall\fR, \fBci\fR, etc will also respect the provided \fBworkspace\fR configuration.116.SS "Using workspaces"117.P118Given the \fBspecifics of how Node.js handles module resolution\fR \fI\(lahttps://nodejs.org/dist/latest-v14.x/docs/api/modules.html#modules_all_together\(ra\fR it's possible to consume any defined workspace by its declared \fBpackage.json\fR \fBname\fR. Continuing from the example defined above, let's also create a Node.js script that will require the workspace \fBa\fR example module, e.g:119.P120.RS 2121.nf122// ./packages/a/index.js123module.exports = 'a'124 125// ./lib/index.js126const moduleA = require('a')127console.log(moduleA) // -> a128.fi129.RE130.P131When running it with:132.P133\fBnode lib/index.js\fR134.P135This demonstrates how the nature of \fBnode_modules\fR resolution allows for \fBworkspaces\fR to enable a portable workflow for requiring each \fBworkspace\fR in such a way that is also easy to npm help publish these nested workspaces to be consumed elsewhere.136.SS "Running commands in the context of workspaces"137.P138You can use the \fBworkspace\fR configuration option to run commands in the context of a configured workspace. Additionally, if your current directory is in a workspace, the \fBworkspace\fR configuration is implicitly set, and \fBprefix\fR is set to the root workspace.139.P140Following is a quick example on how to use the \fBnpm run\fR command in the context of nested workspaces. For a project containing multiple workspaces, e.g:141.P142.RS 2143.nf144.145+-- package.json146`-- packages147   +-- a148   |   `-- package.json149   `-- b150       `-- package.json151.fi152.RE153.P154By running a command using the \fBworkspace\fR option, it's possible to run the given command in the context of that specific workspace. e.g:155.P156.RS 2157.nf158npm run test --workspace=a159.fi160.RE161.P162You could also run the command within the workspace.163.P164.RS 2165.nf166cd packages/a && npm run test167.fi168.RE169.P170Either will run the \fBtest\fR script defined within the \fB./packages/a/package.json\fR file.171.P172Please note that you can also specify this argument multiple times in the command-line in order to target multiple workspaces, e.g:173.P174.RS 2175.nf176npm run test --workspace=a --workspace=b177.fi178.RE179.P180Or run the command for each workspace within the 'packages' folder:181.P182.RS 2183.nf184npm run test --workspace=packages185.fi186.RE187.P188It's also possible to use the \fBworkspaces\fR (plural) configuration option to enable the same behavior but running that command in the context of \fBall\fR configured workspaces. e.g:189.P190.RS 2191.nf192npm run test --workspaces193.fi194.RE195.P196Will run the \fBtest\fR script in both \fB./packages/a\fR and \fB./packages/b\fR.197.P198Commands will be run in each workspace in the order they appear in your \fBpackage.json\fR199.P200.RS 2201.nf202{203  "workspaces": \[lB] "packages/a", "packages/b" \[rB]204}205.fi206.RE207.P208Order of run is different with:209.P210.RS 2211.nf212{213  "workspaces": \[lB] "packages/b", "packages/a" \[rB]214}215.fi216.RE217.SS "Ignoring missing scripts"218.P219It is not required for all of the workspaces to implement scripts run with the \fBnpm run\fR command.220.P221By running the command with the \fB--if-present\fR flag, npm will ignore workspaces missing target script.222.P223.RS 2224.nf225npm run test --workspaces --if-present226.fi227.RE228.SS "See also"229.RS 0230.IP \(bu 4231npm help install232.IP \(bu 4233npm help publish234.IP \(bu 4235npm help run236.IP \(bu 4237npm help config238.RE 0239