How to work on dependency code using NPM link

You might, at some point, find yourself in a situation where you have to work in dependency code. There might be a bug in the dependency, functionality might be extended, or perhaps the code needs refactoring to be more performant.

You could use npm pack to create a dependency.tgz package file when you're ready to test your changes. You would have to link to that file inside your package.json like so:

"dependencies": {
    "component-library": "./path/to/dependency.tgz"
  },

The problem with this approach is that you would have to pack your files every single time you want to test your changes, and you have to remember to put your package.json back the way it was.

Introducing NPM link

I personally think npm link is a cool feature. It creates a symbolic link (symlink) between a package and where you want to use that package. In other words: it connects a package you have locally on your machine to the project you need it in.

Usage

Package linking is a two-step process:

1. Create a symlink¹, or symbolic link, in the global folder by running npm link.
2. Tell NPM in your application to use the global symlink using npm link DEPENDENCY_NAME.

cd ~/projects/dependency
npm link

cd ~/projects/application
npm link dependency

From here on out you can make changes in your dependency's code as you would normally do. Meanwhile, your application will run with the changes you've made without having to update the dependency. Pretty cool, right?!

When you decide your changes are good to go and you're ready to update the dependency, you may want to delete the symlink.

⚠️ Unlinking a dependency with NPM unlink ⚠️

While there is a command called unlink, it doesn't actually behave as you might expect. The npm unlink command is an alias for npm uninstall² and you want to be very careful when using it to delete the symlink.

If you want to properly remove the symlink without uninstalling the package, you'll have to run the command with the --no-save flag:

npm unlink --no-save dependency

This will uninstall the dependency without removing it from your package.json. All that's left to do now is to install the dependency as it's listed inside package.json:

npm install

Good to know

List all linked packages

If you want to find out what packaged you have linked, run this command:

npm list -g --depth=0 --link=true

Speed up unlinking

This might seem obvious for a CLI power-user, but you can unlink and install in one go by chaining commands! Here's how to do that:

npm unlink --no-save dependency && npm install

Final words

I use npm link all the time while working on dependencies for my team. We rely on a bunch of libraries that we've created ourselves and using npm link makes improving them a whole lot easier and faster.

It's been a while since I've written a post, but I hope you've enjoyed it and found it useful!

1. A symlink is a reference, or shortcut, to another file or directory on your system. ↩

2. NPM: npm - uninstall ↩