DEV Community

Reece Daniels
Reece Daniels

Posted on • Originally published at on

Why Your npm link Commands Might Be Failing




When you try to use npm link to install a dependency you’re working on locally, the changes aren’t reflected in your project.

You also see intermittent issues starting your project (esp. in TypeScript), as well as subdependencies not resolving correctly.



There are two issues you can run into when npm link isn’t working which are worth noting;

  1. nvm related issues
  2. Peer Dependency related issues


nvm, or Node Version Manager, is a tool used to run different versions of node locally across microservices at the same time.

When running npm link, the specific version of node being used in the project will be used to create the link, which means only projects using the same version of node will be able to access the local version of the dependency. This can be all the more frustrating because npm link doesn’t throw an error when this happens.

Here’s the readout when using different versions of node (one using 8.9.4, the other using 12.13.1):

/Users/myName/dev/_github/myRepo/node_modules/myDependency ->
Enter fullscreen mode Exit fullscreen mode

And here’s the readout with the same version of node (both using 8.9.4):

/Users/myName/dev/_github/myRepo/node_modules/myDependency ->
/Users/myName/.nvm/versions/node/v8.9.4/lib/node_modules/myDependency ->
Enter fullscreen mode Exit fullscreen mode

Notice how the bottom line resolves to a folder where the dependency resides locally.

To fix this, use node -v in each project and check the running version of node. Use nvm install x.x.x & nvm use x.x.x to match them up.

Afterward, delete your node_modules, delete your package-lock.json, re-run npm i, and re-run npm link in your dependency folder and npm link myDependency in your project folder.

That should help.

Peer Dependencies

If your dependency has references to peerDependencies in it’s package.json you could stumble into issues with symlinks. These manifest themselves in the form of the peerDependency being unablee to be resolved at either compile time or at run time when needed.

The fix for this relatively simple. Add --preserve-symlinks into your start script e.g. node --preserve-symlinks build.

This will instruct your startup script to look in the correct place for it’s peer dependencies when running locally. Note that you’ll want to remove the flag once you’re done testing locally.

Problem (Hopefully) Solved

If you have any questions you’d like to ask me about this post, feel free to reach me on Twitter or Github.

Top comments (3)

ulibka68 profile image
Gayrat Vlasov

Hello, Reece Daniels
Now node 16 is LTS and I'm install it using nvm
With node 16 I'm recieved npm version 8

I'm try all methods, but npm link mypackage don't work with npm 8, but work in npm 6

Are your package work with npm link with npm version 8 ?

rubengmurray profile image
Reece Daniels

Hi Gayrat,

Sorry about the delayed response.

I haven't used npm link with a Node 16 project as of yet so I cannot confirm.

Do you get an error message?

ramonsan profile image
Ramón Orraca

I had a similar issue, first I got this error.

Then I installed the Rollup.js package and got this other error.

I don't understand what the error means, but the link did work and I'm able to use the cowsay package when I run the node file that requires it. What I mean by this is that my node_modules directory contains a symbolic link to the global cowsay package.