How to locally test an npm package
tl;dr I think yalc is the best way to test packages locally before publishing to npm.
If you're working on an npm package, you need to test it locally before you publish it to the registry. I've used all three of these approaches:
npm linknpm pack- yalc
npm link
When you run npm link you create a symbolic link, or symlink, between your local package and a local application. When it works, it's a great way to test local changes to your package.
Unfortunately, running npm link doesn't always work. As Carl Vitullo points out in his blog post, there are three problems with symbolic links:
- Some build tools don’t understand symlinks
- Symlinking doesn’t verify that you’ve packaged it correctly.
- Module resolution doesn’t work with 2 file trees.
I've found that when I try to use npm link I spend more time debugging symlinking than actually testing my local changes. I'd suggest just avoiding this approach in general.
If you'd like to read more about the problems with symlinking, check out this issue from @sebmck.
npm pack
You can use npm pack as an alternative to symlinks. This command creates a .tgz file which you can install in a local application. This is a great approach to testing local components because it mimics the actual process of publishing to npm. When I'm testing a one-off component, or just need to quickly test something, I still often use the pack command.
Carl's blog post has a great example of what a workflow using npm pack might look like, so I'd take a look at that.
yalc
There's a third approach that I prefer to both npm link and npm pack: yalc. According to the yalc documentation, "yalc acts as very simple local repository for your locally developed packages that you want to share across your local environment." Designed to emulate npm pack, I find that it provides a nicer developer experience and makes testing local components more enjoyable than both npm link and npm pack.
Let's walk through what a common workflow might look like using yalc to locally test your changes.
Imagine that I have a library called my-package. First, I need to install yalc globally.
npm install yalc -g
Once I install yalc, I will cd into the my-package directory:
cd my-package
I'll make some changes to my-package that I want to change locally. Once I'm ready to test those changes, I'll run yalc publish.
Next, I'll cd into the project I want to test my component in. Let's call that project my-project.
cd ../my-project
Inside of my-project I'll run yalc add my-package which will install the local version of my-package inside of my-project. And that's it! Now I can run my-project knowing that I have the most recent local changes to my-package installed.