skip to content

In an npm workspaces repo, what does `npm install @rota/date-rules -w @rota/ui` do when `@rota/date-rules` is itself a workspace?

level: middleimportance: must knowfreq 22%

answer

  1. scoped to one workspace
  2. detects the sibling locally
  3. symlink, not a registry fetch
  4. save-prefix plus current version
  5. no workspace: protocol in npm

basics

~20 s

npm detects that @rota/date-rules is a workspace, symlinks the local folder instead of fetching it, writes a plain range such as ^1.0.0 into @rota/ui's package.json and updates the root lockfile; npm has no workspace: protocol.

solid answer

~40 s

The `-w` (`--workspace`) option scopes the install to one workspace, so the new dependency is written to `packages/ui/package.json`, not to the root manifest. Because `@rota/date-rules` is a workspace of the same project, npm links the local `packages/date-rules` folder instead of downloading anything, and saves a standard semver range built from `save-prefix` (default `^`) and the sibling's current version, for example `"@rota/date-rules": "^1.0.0"`. The one root `package-lock.json` is updated, with the sibling recorded as a link. The same flag adds a registry package to one workspace only (`npm install zone-kit -w @rota/date-rules`); `-w` accepts a name, a folder or a parent folder and can be repeated. npm has no `workspace:` protocol, so the range is an ordinary one, and the link holds only while the local version satisfies it.

code

bash · 7 lines
bash
# at the repository root
npm install zone-kit -w @rota/date-rules
npm install @rota/date-rules -w @rota/ui

# packages/ui/package.json now contains
#   "dependencies": { "@rota/date-rules": "^1.0.0" }
# and node_modules/@rota/date-rules links to packages/date-rules

go deeper

for a junior

Remember the command shape, npm install <pkg> -w <workspace>, and that it edits only the named workspace's package.json.

for a middle

Explain what npm writes for a sibling: save-prefix plus the sibling's current version, a link instead of a download, and one root lockfile update.

for a senior

Point out that the plain range is load-bearing: the link holds only while the local version satisfies it, and the same range is what consumers resolve after publishing.

for a principal

Weigh caret ranges against exact versions between siblings: exact pins force a re-save on every release, carets from 1.0.0 up let the link survive minor and patch bumps.

## Scoping an install to one workspace In an npm repository with workspaces, a plain `npm install <pkg>` at the root adds the package to the **root** `package.json`. To add it to one workspace instead, pass the **`workspace` config**, written `--workspace` or its short form **`-w`**. The value can be: - a **workspace name**, such as `@rota/ui`; - a **path to a workspace folder**, such as `packages/ui`; - a **path to a parent folder**, such as `packages`, which selects every workspace inside it. The option can be repeated (`-w @rota/ui -w @rota/date-rules`) to target several workspaces, and the other installing commands, such as `npm uninstall` and `npm ci`, respect it as well. Adding a registry package to a single workspace looks like this: ```bash npm install zone-kit -w @rota/date-rules ``` The new line lands in `packages/date-rules/package.json`, the package itself is installed into the shared tree (hoisted to the root `node_modules` when nothing conflicts), and the one root `package-lock.json` is updated. ## Linking one workspace into another The same command works when the package you name is itself a workspace. In the shift-rota repository, `@rota/ui` needs the scheduling helpers from its sibling: ```bash npm install @rota/date-rules -w @rota/ui ``` npm then: 1. **Detects** that `@rota/date-rules` is a workspace of this project. 2. **Symlinks** the local `packages/date-rules` folder instead of fetching anything from the registry. 3. **Writes a dependency line** into `packages/ui/package.json`. 4. **Updates** the single root `package-lock.json`, where the sibling appears as a link entry. ## The range npm writes The line npm writes is a **standard semver range**, built the same way as for any registry package: the `save-prefix` config (default `^`) in front of the sibling's current version. If `packages/date-rules/package.json` says `"version": "1.0.0"`, `@rota/ui` gets: ```json { "dependencies": { "@rota/date-rules": "^1.0.0" } } ``` With `--save-exact` (short `-E`), npm writes the exact version, `"1.0.0"`, instead. npm has **no `workspace:` protocol**; that range spec belongs to pnpm and Yarn. In npm the plain range does double duty: inside the repository it decides whether the local folder can be linked, and in a published `@rota/ui` it is an ordinary dependency range that consumers resolve from the registry. ## Commands side by side | Command at the root | Manifest edited | What gets installed | |---|---|---| | `npm install zone-kit` | root `package.json` | `zone-kit` from the registry | | `npm install zone-kit -w @rota/date-rules` | `packages/date-rules/package.json` | `zone-kit` from the registry | | `npm install @rota/date-rules -w @rota/ui` | `packages/ui/package.json` | a link to `packages/date-rules` | | `npm uninstall zone-kit -w @rota/date-rules` | `packages/date-rules/package.json` | `zone-kit` removed from that workspace | In every row the lockfile that changes is the root `package-lock.json`. ## Pitfalls worth knowing - **Forgetting `-w`.** The package is recorded in the root manifest, and the workspace that imports it only works because the root's dependencies are visible to it, which breaks once that workspace is installed on its own. - **The range must keep matching.** npm links the sibling only while its local version satisfies the range written in the dependent; bump `@rota/date-rules` to `2.0.0` and `^1.0.0` no longer matches, so npm tries the registry instead. - **Rival syntax.** Hand-writing `"workspace:^"` into an npm project borrows another package manager's protocol; npm does not support it. - **Separate installs per folder.** There is no need to run `npm install` inside each workspace; the root install with `-w` does the work and keeps the single lockfile consistent. ## Checking the result After the install, three quick checks confirm that the sibling is linked rather than downloaded: - **The manifest line.** `packages/ui/package.json` has the new range under `dependencies`, and the root `package.json` is unchanged. - **The lockfile entry.** The root `package-lock.json` has an entry for `node_modules/@rota/date-rules` with `"link": true` and a `resolved` value of `packages/date-rules`, the workspace folder, instead of a registry tarball URL. - **The tree.** `npm ls @rota/date-rules` shows the package resolving to the workspace folder, and `packages/ui/node_modules` holds no separate copy of it. If any of the three disagrees, the most common cause is a range that no longer matches the local version, or a `-w` value that selected a different workspace than intended; a `-w` value that matches nothing at all stops the command with a `No workspaces found` error. Whether the repository should hold all these packages, and how build order across them is managed, are separate questions; this is only how npm records and links one package's dependency on another.

  • What changes if you add `--save-exact` to the same command?
    npm writes the sibling's exact version, `"1.0.0"`, instead of `"^1.0.0"`. The workspace is still linked while that version matches; the difference is that any later version bump of `@rota/date-rules` breaks the match at once, so the dependent's line has to be re-saved with every release.
  • How do you add the same registry package to two workspaces in one command?
    Repeat the option: `npm install zone-kit -w @rota/ui -w @rota/date-rules`. The `workspace` config can be set several times, each named workspace gets the line in its own `package.json`, and the shared copy is installed once where hoisting allows.
  • How do you remove a dependency from only one workspace?
    Use the same option on the removing command: `npm uninstall zone-kit -w @rota/date-rules` deletes the line from that workspace's `package.json` and updates the root lockfile. Other installing commands, `npm ci` included, respect the `workspace` config too.

  • npm writes a workspace:^ range when one workspace depends on another.
  • The -w option only accepts a folder path, never a package name.
  • npm downloads the sibling from the registry, then swaps in a link later.
  • A plain npm install zone-kit at the root adds it to every workspace.
  • Each workspace needs its own npm install run inside its own folder.