At work, we have our own npm packages that we manage and maintain. As part of the dev process its crucial to test out the package in the context of a larger project to ensure it functions as expected and meets all our criteria. A handy trick that I've been using is linking local npm packages using npm link
.
However, as a result of having multiple tasks on the go on any given day, I kept getting myself into weird situations with permission issues where I would have the package not available anymore, which TBH was v annoying. The result of constant branch switching and not cleaning up my local environment before doing so.
Here are the exact steps for both linking and unlinking so you can avoid the #struggle I went through.
Lets say we have an npm
package that we are working on locally, lets call it cowabunga
. Our project structure looks something like this:
And it’s package.json
file looks something like this:
You’ll notice that this package has its own node_modules
folder - this is where I kept getting tripped up. I would switch branches in the repo where my package lives and the node_modules
folder would disappear as a result of building other components that don't live in both branches. When I would go to unlink, npm was throwing permissions errors that went something like this:
npm ERR! enoent ENOENT: no such file or directory, access ‘my_project/node_modules/cowabunga/node_modules/some-package’
In order to avoid this, you have to follow the linking/unlinking order otherwise npm will try to unlink folders that no longer exist. Seems pretty basic but it was surprisingly tedious to figure out.
Linking:
First, in the cowabunga folder (where package.json is):
npm link
Then in the project you want to include cowabunga in:
npm link cowabunga
Unlinking:
Before switching branches and/or removing any node modules from the package itself (in my project, this includes running learn clean
which removed the node_modules
folders)
First, in the project:
npm unlink --no-save cowabunga
Second, in the package:
npm unlink
Note: order is important!
Where I kept running into issues is switching branches and then the symlink couldn’t find the package anymore so you were stuck in this weird state where you couldn’t link anything or unlink anything because the folders don’t exist. When this happens, check out your original branch and start from the beginning with linking the package and the project.
🤙
Bonus:
You can also run
npm install -g i .
in your package folder to install it globally and avoid some of the linking mess 🎉
Top comments (14)
Came across a similar linking issue and I wasn't able to fix it via unlinking, I had to resort to deleting the package-lock.json :(
Also, in case you weren't aware another way to npm link is to be in the directory of the project and then
npm link ../../package-directory
. I like it for saving me a stepThanks Erin! This is exactly the situation I found myself in. Appreciate the write up!
Out of curiosity though -- why is the
--no-save
flag important?Looks like
unlink
is an alias foruninstall
, so the--no-save
means uninstall, but don't remove fromnode_modules
?Yep! If you don't include
--no-save
you'll end up removing that package from your package.json file. Of course, if you don't want to include the unlinked package in your package.json file, you can exclude the--no-save
Found this helpful - medium.com/dailyjs/how-to-use-npm-...
Also... let's say you do goof and get the
ENOENT: no such file or directory, access '/...
error... then what?What I've had to do is go back to whatever state has the files/folders that npm is looking for. So let's say you have a package that is on one branch and not on another, you'd have to go back to your other branch and run
npm link
again for that package before runningnpm unlink my-package-name
in your main projectYou may also go to the folder where the symbolic link library is installed and deleted the folder.
Hi Erin! Thanks for explaining this topic more.
What is
npm install -g i .
doing? I understand that it is installing the package globally with the-g
and the.
is taking all the files from the current directory. Specifically, what isi
? Is this an alias? And why do you add it here?Is the
i
referring to the NPM at this link npmjs.com/package/iIs there a reason to install
i
along with the folder where package.json is located?Whenever I run
npm unlink
in my package folder, it removes a lot of global node modules...I am not able to understand what exactly is happeningAwesome post! I also dislike the fact that the
--no-save
option is needed. I rannpm unlink
without it and now I can't use the original package anymore... 😢if I delete link package how to delete symbolic link?
Hey Erin, i found this really helpfull. But i broke the pipeline by sending the push with the linked custom package. So i hope no one did that