Testing npm packages before publishing2018-07-27
¶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 firstname.lastname@example.org, 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.
¶Some build tools don't understand symlinks.
¶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.
¶Symlinking doesn't verify that you've packaged it correctly.
¶Module resolution doesn't work with 2 file trees.
¶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.
¶Now, I use npm pack.
¶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.
~/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
¶You could probably set up an alias or function in your terminal to automate this, but I don't do it frequently enough to bother. npm pack | tail -n 1 will output just the filename to standard out.
¶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!