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:
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.
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.
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
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.
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
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.
Once I install
yalc, I will
cd into the
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
cd into the project I want to test my component in. Let's call that project
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
Hungry for more?
Do you want design systems tips and tricks sent to your inbox?