Chris Bongers

Posted on Jul 29, 2021 • Originally published at daily-dev-tips.com

How to test your NPM package locally

#npm #javascript #testing

We made our very first NPM package, and briefly touched on how to test it locally.

However, I felt this needs some more explanation.
As I hit this wall when making my NPM package.

You don't want to be that person pushing new versions just so you're able to test if something works.

And trust me, I did this 🤦‍♂️.

Link your NPM package locally

The first step is to open a terminal and navigate to your NPM package on your machine.

Now execute the following command in the terminal:

npm link

This command will link this local package to your globally installed packages.

Import the link in a test project

On the other side, we need to link this package to the test project we want to try it out in.

Navigate to the test project and execute the following command.

npm link {package-name}

I named my package npm-calculator, so I have to run:

npm link npm-calculator

Now, if we look at our node_modules, we can see this is a symlink now!

Now let's also actually try if it works. By creating a test index file, we can import our NPM package.

const {add, subtract, multiply} = require('npm-calculator');

console.log(add(1, 5));
console.log(subtract(10, 5));
console.log(multiply(2, 6));

When we run the code now, it works. Our NPM package is loaded and worked locally.

To try this out, edit your NPM package by, for instance, adding a console log. This is just for the sake of testing the local link.

I'll add a log in the add function.

Now without doing anything, head back to your test app and re-run the code.

As you can see, our change works right away!
This makes for a much quicker development experience.
And again, once you're happy with this, you can go ahead and publish your NPM package to the registry.

Thank you for reading, and let's connect!

Thank you for reading my blog. Feel free to subscribe to my email newsletter and connect on Facebook or Twitter

Top comments (14)

Andrei Luca • Jul 29 '21 • Edited

Some things to take into consideration. Let's supose that your npm-calculator also depends on react and your npm-calculator-test also depends on react
you will have react installed in 2 places

npm-calculator/node_modules/react
npm-calculator-test/node_modules/react

Now when you use npm-calculator it will load react from here

npm-calculator/node_modules/react

Instead from here

npm-calculator-test/node_modules/react

because of how modules are resolved. And you may encounter strange errors.

To fix this you will need to tell your bundler to resolve all dependencies from npm-calculator-test/node_modules/** instead of npm-calculator/node_modules/**

webpack.js.org/configuration/resol...

webpack.config.js

module.exports = {
  resolve: {
    alias: {
      react: resolve(__dirname, 'node_modules', 'react'),
    },
  },
}

And now every import of react should be loaded from here npm-calculator-test/node_modules/react

David • Sep 21 '22

Just use PNPM

Jack • Jul 30 '21

This isn't quite true. Npm is smart enough to resolve common versions of packages so if they both depended on the same major version of react, it would be fine.

This is probably a bad example, though, as 99.9% of the time react would be a peer dependency instead (which completely alleviates this problem and gives the version responsibility to the consumer)

Andrei Luca • Jul 30 '21 • Edited

I have to mention again, that this is a specific use case when you use npm link

Unfortunately that's true. NPM is just a package manager, install/uninstall dependencies. Node is the one who resolves dependencies.

nodejs.org/api/modules.html#module...

Smart enough should be the bundler to know what exactly to load.

github.com/iamandrewluca/example-n...

cd npm-calculator
npm install
cd ../npm-calculator-test
npm install
node index.js

17.0.2
16.14.0

Jack • Jul 30 '21

I mentioned it in another comment but in my experience, npmjs.com/package/yalc solves all of these kind of issues. It's so useful

Chris Bongers • Jul 30 '21

Thanks Andrew! This is a useful addition actually!
I would have thought NPM would resolve only one of the dependencies based on it's version checks it does.

Andrei Luca • Jul 30 '21 • Edited

Created a small demo here github.com/iamandrewluca/example-n...

cd npm-calculator
npm install
cd ../npm-calculator-test
npm install
node index.js

Outputs

17.0.2
16.14.0

Junxiao Shi • Jul 29 '21

npm link cannot catch errors in package creation, such as missing a necessary file in package.json "files" property.
I test my packages with npm pack as tarball, or by publishing to a private Verdaccio registry.