(image credit: Erol Ahmed)
When developing an npm package, you have to confirm that it can actually be used. It's great if tests pass, examples build, and demos run, but it's broken if consumers can't install it. npm provides a tool to help test packages before publishing, npm link. The docs explain it very well, but a small example is below. You run it once in your package directory, and again in your app directory.
~/workspace/package-name $ npm link ~/workspace/some-application $ npm link package-name
This is an excellent option–when it works. npm link has been around all the way back to email@example.com, long before build steps were the norm and browser JS was a part of npm, and the adoption of these tools has introduced some problems. There are 3 main problems I've run into.
Mature build tools typically don't have this problem or have issues with symlinks discovered and fixed quickly. However, it's a common problem with newly released tools and one of the more common regressions. webpack has special configuration for how to resolve symlinks because of these issues. The documentation specifically mentions potential problems with npm link.
This is the most damning problem. It's one thing to have tools break occasionally, but for an entire category of libraries, npm link is fundamentally incompatible. These problems have put me off using npm link at all. I have wasted numerous hours trying to wrangle symlinks for a package I'm developing and have never gotten it to a point where it's reliable.
The pack command creates a .tgz file exactly the way it would if you were going to publish the package to npm. It pulls the name and version from package.json, resulting in a file like package-name-0.0.0.tgz. This can be copied, uploaded, or sent to a coworker. It's exactly the file that would be uploaded to npm if you published it.
~/workspace/package-name $ npm pack
Once you have the file, you can install it. npm install can install from a lot more sources than just npm, and I highly suggest skimming through the docs. We have to specify the full path to the file, so I usually copy it to my home directory first for convenience. Update: Since originally writing this, I've been informed about yalc, a tool to automate the worflow I describe here.
~/workspace/package-name $ npm pack ~/workspace/package-name $ cp package-name-0.0.0.tgz ~ ~/workspace/some-application $ npm install ~/package-name-0.0.0.tgz
This runs through a complete publish cycle–it even runs the publish npm script and the associated pre- and post-scripts. Packing it up and installing it is an excellent way to simulate publishing a package, and it avoids all of the quirks and problems of symlinking.
I know when I was first trying to publish packages to npm, one of the hurdles I faced was figuring out if it would actually work. Publishing feels so final; you put it up for the world to see and that version number can never be used again. npm pack helps me be more confident that it's going to work the way I expect it to.
Thanks for reading! I'm on Twitter as @vcarl_ (but most other places I'm vcarl). I moderate Reactiflux, a chatroom for React developers and Nodeiflux, a chatroom for Node.JS developers. If you have any questions or suggestions, reach out!