npm / npm/cli

[BUG] `npm --workspace=<ws> link <path>` doesn't setup symlink in workspace

Open
#9,115 2 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Bug Priority 2
Dominant language
JavaScript
Stars
10.1k
Forks
4.7k
Avg merge
2d 2h
Merged PRs (30d)
19

Description

Is there an existing issue for this?
  • I have searched the existing issues
This issue exists in the latest npm version
  • I am using the latest npm
Current Behavior

My project contains two workspaces that import the same dependency in the same version.
After running the npm ci command, the top-level node_modules directory contains this dependency. The node_modules directories in each workspace do not contain this dependency, which is the expected behavior.

 .
├── workspaces
│   ├── workspace1
│   │   ├── node_modules
│   │   └── package.json
│   └── workspace2
│       ├── node_modules
│       └── package.json
├── node_modules
│    └── <dependency>
│         └── package.json
└── package.json

When I want to use the local version of a dependency in a single workspace, I run the command npm --workspace=<ws> link <path>. Once the command has been successfully executed, a symbolic link is created in the top-level node_modules directory, and workspaces that have declared this dependency will have the version of the dependency specified in the package.json file (published version) in their node_modules directory.

.
├── workspaces
│   ├── workspace1
│   │   ├── node_modules
│   |   │   └── <dependency>
│   │   |       └── package.json
│   │   └── package.json
│   └── workspace2
│       ├── node_modules
│       │   └── <dependency>
│       |       └── package.json
│       └── package.json
├── node_modules
│   └── <dependency> -> /path/to/dependency
└── package.json
Expected Behavior

When I use workspaces, I would like the npm link command to create a symbolic link in the target workspace(s).

For example, for the command npm --workspace=workspaces/workspace1 link /path/to/dependency, I expect that:

.
├── workspaces
│   ├── workspace1
│   │   ├── node_modules
│   |   │   └── <dependency> -> /path/to/dependency
│   │   └── package.json
│   └── workspace2
│          ├── node_modules
│          └── package.json
├── node_modules
│   └── <dependency>
│          └── package.json
└── package.json

In this configuration, workspace1 is built using the local version of , whereas workspace2 uses the published version.

Steps To Reproduce
  1. Clone the repository to get a working example. The repository is hosted on my account: https://github.com/baptistedonaux/npm-cli-workspaces-issue
    git clone git@github.com:baptistedonaux/npm-cli-workspaces-issue.git
  2. cd npm-cli-workspaces-issue && npm ci
  3. Set up a local dependency to link it. You can use lodash as specified in the package.json.
    git clone git@github.com:lodash/lodash.git /tmp/lodash
  4. npm --workspace=workspaces/foo link /tmp/lodash
  5. To view the configuration of node_modules and dependencies, you can run this command:
    ls -l node_modules workspaces/foo/node_modules workspaces/bar/node_modules
Environment
  • npm: 11.9.0
  • Node.js: v24.14.0
  • OS Name: node:24-alpine Docker image hosted on Fedora 43
  • System Model Name: Linux
  • npm config:
; node bin location = /usr/local/bin/node
; node version = v24.14.0
; npm local prefix = /
; npm version = 11.9.0
; cwd = /
; HOME = /home/node
; Run `npm config ls -l` to show all defaults.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the behavior with npm ci followed by npm --workspace=workspaces/foo link /tmp/lodash, then inspect how the npm link command handles workspace targets. Compare the resulting top-level and workspace node_modules directories with the expected layout; done means only the selected workspace points to the local dependency while other workspaces retain the published version.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, node.js
Domain
cli, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
64/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.