How to Npm Link Local Package: Use Yalc as Npm Link Alternative

How to Npm Link Local Package: Use Yalc as Npm Link Alternative

Use yalc and test npm packages locally like a boss

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.

If you have never worked or heard of npm link before, let's first briefly define it.

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 link in 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_modules folder 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.

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.

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-one and 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:

cd ~/projects/project-two

First, go into the project-two directory

npm link

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.

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
npm install

In case, if these two commands don't work for you, you can easily do it by running:

rm -rf node_modules
npm install

This will completely remove the node_modules folder and install a fresh one without linked packages.

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 yarn and 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.

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

file: .yalc/dependency-package

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:

yalc publish

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:

  • npm link

  • yalc

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.