Inside NPM: Building and sharing JavaScript packages

The Node Package Manager, NPM, has become a powerful and important tool, supporting many different JavaScript frameworks — including JQuery, AngularJS, and React JS. If you’re building JavaScript modules and want to share them with the world, NPM is the tool to use.

With a public registry for your code, NPM makes it easy to share code and ensure users can get updates quickly. With small NPM packages, the result is another set of tools for building modular code that’s simple to reuse across your applications, both server-side and client-side.

The NPM registry is a database of modules, showing not only what packages are available, but also how they’re related. When you download a module — the Express Node.js MVC framework, for instance — you automatically download the dependencies, so you’re ready to go as soon as all the files you need are installed on your development system.

Roll your own package

Building an NPM package is a relatively simple process since you use the tooling built into NPM itself. Start with NPM’s init command to build the package.json file for your application. You’ll need a name, a version number, and a main .js file. It’s also a good idea to add a name and a contact email address for support.

This will create a stub package.json file that can then be edited to add the details of all the files you’re packaging for distribution. You can test your files using NPM locally, but once you’re ready to share a file with the world you’ll need an account on the NPM registry, which you can create using NPM’s adduser command.

What goes into an NPM package? The heart of it is a Gzipped folder, containing the files used by your module. You’ll need to store it on a public server, like GitHub or your own servers. (Going with a service like GitHub makes a lot of sense, because one packaging option is to link to a source control service that can be used to share open source code quickly and easily.)

You’ll also need a fully detailed package.json file. This includes your project’s name, its current version, and the engines it runs on. This last option lets you specify a version of Node, AngularJS, or whatever to ensure your code will run as expected. Many open source frameworks change rapidly — for example, if you have a dependency on a specific version of Node, then NPM will ensure that your code can be installed on that version only.

Other key fields in package.json handle scripts used to install your files or run other commands to ensure target systems have the appropriate prerequisites that aren’t described by only. You’ll also need to specify an entry point for your code … if there is one. Packages that contain several scripts won’t need an entry point, but they’re likely to need documentation, which you can bundle in a main folder that can be set up by NPM.

It’s important to note that although NPM won’t bundle all your files, it’s a good idea to use a .npmignore file to ensure that specific configuration and log files aren’t packaged up. For example, you don’t want to include your AWS keys, nor do you want your personal documentation to end up on a million cloud servers!

Pushing the package live

Publishing a package is simple: Use the publish command. You’ll need a unique name for your package, as the NPM registry uses it to construct a URI for your files, which you can test in a browser.

Updates can be made using the version command, describing the update as a patch, a minor update, or a major release — NPM will automatically update the version number of your package, before you publish the updated files. Semantic versioning like this is a powerful but simple tool, and it’s used to define any dependencies in a package.

Once you’ve built a package, you can quickly test it with a local install into another directory. You can then test the module you’ve installed to ensure all the files you need are in the package and that extraneous files aren’t wrapped and delivered. If it works, then you’re ready to publish your package and link it to the NPM registry.

Listing your package’s dependencies is important. You might know that your code is designed to run on top of version 1.2.0 of Express, but someone finding a link to your package might be running version 1.1.5 and won’t be able to use your code.

With NPM, you can use the package.json file to list dependencies, with the package name and the version number. When NPM installs your package, it will check for the engine you’ve required, and if that isn’t present, the install will fail. If the correct engine is available, it will then check the versions of the required dependencies, downloading the most appropriate version where possible. If the required version isn’t available, then the installation will fail.

You don’t need to be specific with version numbers. If your code will run on all the minor and patch versions of a package, then you can specify 1.x.x. Similarly if you have a dependency on a specific minor version, but not patches, then use 1.3.x. You  have the option if using the >= syntax to specify any version greater than or equal to a specific version number, but that leaves you open to the risk of breaking changes in a future release of a package. Thus, it isn’t recommended.

You’ll find the package.json file used in other tools as well as NPM. Mozilla has a version for Firefox add-ons, and it’s being used by the CommonJS server-side JavaScript project. While the public version of NPM allows you to share your code widely, there’s also the option of running a local registry that can manage business-specific code without exposing it to the world.