Publishing a JavaScript Library - for Dummies

Publishing a JavaScript library can be overwhelming these days. You want to reach a crowd as broad as possible, but there are dozens of different approaches existing and choices to be made. This article is a quick summary of current best practices, which are developing with npm, and publishing via npm and Bower package managers as well as a universal standalone distributable file. To follow, you need to be familiar with npm.

In the good old times when Prototype and jQuery were competing for the default JS framework, publishing a JS library was easy. Provide a download of the .js file somewhere, optionally add a fancy minified version, and specify the dependencies on other libraries that had to be present. Potential users would manually download the file (CDNs were just starting to be used), add it to their project, take care that the dependencies were met, and hopefully get it to work. Today, there are dependency managers that just require a single install command and take care about (almost) everything else. This of course requires some legwork to be done by the developer, which isn’t too straightforward as I recently found out. In an experiment on publishing a simple JS library called gallerygrid.js, it took me quite some time to learn how to publish it, almost more than the actual time needed to develop it. This guide sums up the current best practice and required steps to publish a JavaScript library.

Developing with npm

Choosing the right environment simplifies not only development but also the publishing process, and the right choice and current de facto standard is npm. The Node Package Manager (originally written for Node.js) facilitates sharing and reusing of already existing code. It provides almost every module/library you will ever need and there are even packages for the most simplistic of functions, whose usage is certainly a question of individual preference. An interesting read on exaggerated npm use along with an interesting discussion on pros and cons in the comments is available here. Modules follow the CommonJS pattern to import modules through require(...) and export them through module.exports = .... See this example JS file for reference.

Publishing through npm, Bower, and as standalone file

Publishing is complicated if you want to support all kinds of platforms and build tools. To reach most developers, it suffices to provide packages through npm and Bower, and a standalone file following the Universal Module Definition. Although some people discourage Bower support and there are also disproved rumors making the rounds that Bower has been abandoned by its core devs, it is still the current standard package manager for frontend development. So if you developed your library with npm or at least followed the CommonJS export pattern (if you don’t require any dependencies), then this part is going to be straightforward. The npm package is basically finished and just needs to be submitted to the registry. From the npm module we generate a standalone version, that we finally publish to Bower.

npm

To publish your library through npm, you basically just need to have an account at the npm registry, create and configure a package.json file (by copying an example file or executing the npm init command), and submit it by running npm publish. Details on publishing are available in this nice article which I recommend to read carefully, and instructions on pushing an update are available in this follow-up article.

Standalone UMD file with Browserify

A Standalone file is a JS file that can be used in the plain old way of downloading or including it from a CDN. It is working on its own, and might require dependencies in the form of other standalone library files. Standalone files are usually distributed as normal and minified versions. If a standalone file follows the UMD pattern, it can be also be conveniently used in various modularized server and client side platforms. Conversion from npm module to standalone UMD file is done with Browserify (available through npm) and its standalone option, i.e. browserify foo.js --standalone Foo > standalone.js. Browserify takes a module and all its dependencies and puts them together into a single file. I recommend setting up a build script with Gulp (also available through npm) that automatically creates the standalone version and its minified pendant. See this example gulpfile.

If a standalone library depends on another popular library that a developer will most likely already use, e.g. jQuery, I recommend to exclude this module from the browserified version and mention the dependencies and required versions in the documentation.  This saves duplicate code and keeps the file size of the library as small as possible.

Bower

Once the standalone version is there, it can be published to Bower.io. The process is very similar to npm, except you don’t need an account and create a bower.json from an example file or with bower init. In the configuration file, you need to specify all dependencies that have been excluded from Browserify and set the standalone non-minified file as main entry point. Instructions on initial publishing and updating Bower modules are also available in the same articles linked in the npm section above.

Conclusion

Npm and Bower are the current standard that you need to care about. This article has given directions on how to publish to them and on how to create a standalone file for old times’ sake. Alternative platforms most probably provide compatibility layers (converters, transformations, …) for these modules or at least for the UMD standalone file. That’s it, happy publishing!