Publishing your first Browserify/Node module

NPMnpm is a software registry that serves over 1.3 million packages. npm is used by open source developers from all around the world to share and borrow code, as well as many businesses. There are three components to npm: the website the Command Line Interface (CLI) the registry Use the website to discover and download packages, create user profiles, and... has just surpassed the 100.000-packages milestone while more and more packages can be run in the browser as well (the so called isomorphic JavaScript). If you have not published a module before, this article is definitely for you.

To be able to run node packages in the browser you need either Browserify or Webpack. In this article we will go with Browserify.

To install Browserify open a terminal and type:

npm install -g browserify

Hello Browserify

To get started with your first Browserify module, let’s create a file containing:

// main.js
var $ = require('jquery');
$('body').append('<p>Hello Browserify!</p>');

Then run:

npm install jquery --save
browserify main.js -o bundle.js

Wow, what just happened? First, we required jQuery, which will be looked up from the node_modules directory. So to place jQuery there, we installed it from NPM. The last thing is to create a bundle with the browserify command.

Also, if you want to create your bundle on each file change you can use watchify.

After this, create an HTML file and include the script:

<script src="bundle.js"></script>

The Hello Browserify should be appended to the body of the HTML page.

Setting up a package to publish

After you have just created your very first browserify module, it is time to set up a project – a project that can be published to NPM.

To init a project with NPM, you should use:

npm init

This will ask for the project name, description and some basics. Fill them out! 🙂

Something like this should be in your package.json:

{
  "name": "MyFirstModule",
  "version": "1.0.0",
  "description": "Gonna be great",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Gergely Nemeth",
  "license": "ISC"
}

Adding functionality

In the generated package.json the main property tells NPM which is the entry point of the application. In this case it is the index.js file. The logic of your module should be here – it is also common to put everything under ./lib/ – in this case your index.js would only be like this:

module.exports = require('./lib');

Test-all-the-things!

Make sure to provide test cases to your library – it not just helps people to contribute to it but can easily become the documentation for it as well.

More on testing can be read at our guest post at the Joyent blog.

Run your tests

Running your tests not just against Node.jsNode.js is an asynchronous event-driven JavaScript runtime and is the most effective when building scalable network applications. Node.js is free of locks, so there's no chance to dead-lock any process. but different browsers is essential to make sure everything works everywhere.

For testing let’s use tape.

For Node.js

To run your tests in Node.js Travis is a great choice – also it is free for open source projects.

Setting up just takes a .travis.yml file:

node_js:
  - "0.10"
  - "0.11"

It will run npm test, so make sure the scripts part of your package.json has one for testing, like:

"scripts": {
    "test": "tape test.js"
  }

The only thing left to do is to set up a commit hook on GitHub to enable Travis. (Settings > Webhooks & Services)

For the browser

Testling is kind of the same thing like Travis, but tailored for the browser.

Setting up takes a little bit more effort as you have to define the browsers to run against:

"testling": {
    "files": "test/*.js",
    "browsers": [
      "ie/6..latest",
      "chrome/22..latest",
      "firefox/16..latest",
      "safari/latest",
      "opera/11.0..latest",
      "iphone/6",
      "ipad/6",
      "android-browser/latest"
    ]
  },

To enable Testling the only thing is left is to enable webhooks on GitHub like we did with Travis. If you need more info, check the official site.

Publishing

We have the tests, we have functionality – publish it!

To do so you only have to give this command to npm:

npm publish

This will create a tar from your module and publish it to NPM.

Things to consider:

• it is great that you have tests, but to run your module you may not need them – for this reason you can use the .npmignore file
• you cannot republish the same version – if you change something please bump the version number in your package.json accordingly to Semver.

Example project

An example project can be found in our GitHub repository: https://github.com/RisingStack/your-first-browserify-module

If you have any questions, do not hesitate to create an issue there or comment here!