Table of contents
During the development phase when a team is developing a specific npm package, in order to update and push the newer version of it, you would need to test the npm package locally first before making the changes public.
Similarly, your team may work on different projects that include diverse npm packages of your own and the changes you've made in one may be of breaking nature. In addition, you are making yourself a problem when in reality you can simply npm link your local package and test the changes in the other.
Throughout the years, developers used to utilize the npm link command that gets installed as an internal part of the node package manager (NPM). Truth be told, it has been of great value making the testing part significantly easier. However, it's not all fine and dandy about it, probably expected.
In the listed chapters below, we will cover and tackle first the npm link command, illustrate its use, then talk about potential issues you may run into, and see why you should go for yalc, a remarkably popular npm tool, instead.
What does npm link do?
If you have never worked or heard of npm link before, let's first briefly define it.
What is npm link?
Npm link is a handy command that you can use for installing your own private npm packages so that you can work and test those projects iteratively without having to continually rebuild.
The package linking process consists of two steps.
First, you need to run
npm linkin a package folder that you want to test, which will also create a symlink in the global folder that links to the package where the npm link local package was conducted.
Second, when you want to use that local npm package in another project, you just have to run
npm link package-name. As a result, this will create a symbolic link between the globally-installed package and the
node_modulesfolder of the current project.
Importantly, make sure that you always write the package-name as it is defined in
package.json, and not from the directory name.
How to use npm link?
Npm link is a fairly easy command to remember and run, and it does the job well most of the time. If you still feel a bit unsure or find it slightly challenging to grasp and feel confident to use in your projects, don't worry as we will go through an example below.
Npm link example
Let's assume that you're working on a new project (package) but it's still in early development so you don't want to publish it anywhere public. In other words, you want to test the npm package locally for a while before you decide to publish it to npm and make it public.
What you need is, in short, a means to somehow link the npm package locally with another project of yours and test all the functionalities. By this, you can see whether everything is working as expected and get good feedback.
Let's say, we have a
project-two. Both projects are public on npm and if you want to install them, you can do that by
npm install command. But what if we have made some changes to the
project-two and we want those changes to be applied to the
project-one? Should we rebuild
project-two, push the changes and then run
npm install again in the
project-one? That's not how it's supposed to be, clearly...
We want to npm install our local package that we're working on without having to do any rebuilding and publishing to npm.
There is a solution. Follow the steps below:
First, go into the project-two directory
This will npm link local package and create a global symlink
cd ~/projects/project-one Now let's open the project-one directory
npm link project-two
After you reproduce the steps above, now any changes you make in
project-two will be reflected in
~/projects/project-one/node_modules/project-two. Note that the link should be to the package name, not the directory name for that package.
How to remove npm link?
If you are done and no longer need a local version of the package, you can remove the link between them by running:
npm unlink project-two
In case, if these two commands don't work for you, you can easily do it by running:
rm -rf node_modules
This will completely remove the
node_modules folder and install a fresh one without linked packages.
What if npm link is not working?
Npm link is a useful command whenever you test npm package locally, but it doesn't mean that it will always work flawlessly. What do I mean by that?
Well, even though you follow the steps, as explained in the official docs, you may run into some unexpected and weird issues. Therefore, in order to test npm package locally, sometimes you are forced to search for an alternative or another way.
Fortunately, there is an excellent npm link alternative, and I recommend you to go for it if you find
npm link confusing or difficult to set up.
In the following chapter, I will briefly introduce you to
yalc, an npm package that helps you link local packages to other projects.
What is yalc?
As the about section claims, you can utilize the power of yalc to work with
npm packages locally like a boss.
With pretty straightforward commands, yalc operates as a simple local repository for your locally developed packages that you may want to share across your local environment. Undoubtedly, it's my go-to tool when it comes to testing npm package locally.
How to use yalc?
When you run those commands, yalc will create a special
yalc.lock file within your project that ensures consistency while performing yalc's routines.
First, you have to install yalc globally, so you can use it throughout your projects:
npm i yalc -g
yarn global add yalc
Publish your package
If you want to test your package locally and propagate its changes to other projects, you need to run
yalc publish in your dependency package.
yalc publish package-name
This command will copy all the files from the dependency package, that should be published in the remote npm registry.
Link the dependency package to the dependent project
yalc add dependency-package
This command will copy the current version of the dependency package from the store to your project's yalc folder. The newly generated .yalc folder will inject
into package.json. You can even get more precise and specify a particular version of the dependency package:
yalc add dependency-package@version
Propagate new changes to the dependent project
First, run this command in the dependency package:
And then, make sure to update those changes in the dependent project:
yalc update dependency-package
Remove the linked local package
yalc remove dependency-package
yalc remove --all
If you want to remove all packages from the project.
Hopefully, your understanding of the npm link command has significantly improved after reading this article.
In case you need to npm link a local package to another project and test it locally, you can choose between:
Personally, I favor
yalc because I have never had any weird issues and it has worked in every situation. However, if you prefer
npm link, you can stick to it. But, it may not work for you all the time.