A Couple Ways to Test NPM Packages Locally

Testing NPM Packages locally is a necessity when doing Package development. You want to be able to install it into an example project and then see if everything works as expected. There are a couple ways to do this, some simpler, some prone to headaches.

Below are a couple ways to test packages locally and some of the possible issues associated with each.

NPM Publish

This method is probably the most traditional. Make your change, publish your package, and then re install your package into your test project. I do not need to explain why this is a dumb method. My advice is to “not do this please”. It is time consuming and litters your NPM registry with a lot of broken versions.

NPM Pack

This method is similar to NPM publish but more practical and faster. Basically you build a tarball file of your package locally. You can then install it manually in your test project.

npm pack

NPM Pack will generate a Tar file. You can then copy the url path and install it into your test project.

npm install "../../Users/username/[some path]/test-package.tar"

This will manually install the package into your project. The issue is still the same as the “NPM Publish” method. When ever you make changes you have to npm pack again and reinstall the package. I would not use this method for active development. It should only be used if the next method has issues and you need a quick test before publishing.

NPM Link

This is the elegant and best way to do local package development. It creates a sym link from the package and allows you to create a live link from the package to your project. Its like actually just installing the package except its not…. Another great reason for linking modules with npm link is they are dynamic. The module does not need to be recompiled every time you make a change. If your build tools are set up correctly, like in Create React App or Next.js, then when you make a change to your module the change will automatically be reflected in the project. So amazing! Steps on how to do this below.

Create a sym link from your module. Go ahead and cd into your module directory and run…

npm link

This will create a sym link from this directory.

Then go to your project and install your package by..

npm link [some-package-name]

This will install a link into your project’s node-modules folder for this package without actually installing it.

Issues with NPM Link

Though NPM Link can be magical, it can also be very cantankerous. Like a really grumpy Unicorn. I listed some issues I have ran into in the past with some possible solutions.

Issue: You have to relink your module every time you do an `npm install` or `npm update`. This can get tedious if there are a lot of linked packages.

Solution: Create a npm task to automate linking your packages every time they unlink.

Issue: Linked packages can cause package conflicts in your project. I have especially ran into this with React projects where the linked package and the project it is linked to use different versions of React in their dependencies. This can cause a lot of frustrating issues.

Solution: A way to resolve this is to put your problem dependency in the peer dependencies of your linked module, so it will use your project’s dependency instead.

Issue: For Typescipt projects this could cause type errors as Typescript is not able to pull type declarations from peer dependencies.

Solution: If your peer dependency uses @types then you can just install that. If the declarations are bundled with the dependency then you will need to globally install the peer dependency and move your projects dependency to peer dependencies as well. So both the linked package and project will share the same dependency globally.


And there you go. NPM Package development does not need to be difficult and tedious, especially when using methods like npm link.

Default image
David Sanders
My name is David Sanders. I am a Web Developer and Graphic Designer. My specialty is React.js application development and UX Wireframing. I am the creater of the Treble Global State Management System for React and continue to develop and maintain the project. I also love black coffee.

Leave a Reply