Create NPM Package – Node.js Module

How to create NPM module package

Want to publish your Node.js module to the public NPM registry? I'll show you how to do so using an example. Yesterday I created a module called flv2mp3 for converting FLV files to MP3 files. Let's put it up on the NPM registry for the world to be blinded by its technical splendor.

Publishing a Node module involves working with two networks - a remote repository and the NPM registry. The remote repository in our case will be the flv2mp3 GitHub repository.

The original source of the GitHub project on my Ubuntu box (flv2mp3 directory) looked like this:

-rwxr-xr-x 1 hacksparrow hacksparrow 1024 2012-02-25 22:38 index.js
-rw-rw-r-- 1 hacksparrow hacksparrow  471 2012-02-25 23:56 package.json
-rw-rw-r-- 1 hacksparrow hacksparrow 1035 2012-02-25 23:02 README.md

index.js is the Node.js script that handles the user interaction and media conversion process.

package.json is the module meta data file. It contains the details about how your module works. I have kept it very minimal, but you can add more options if required.

{
    "name": "flv2mp3",
    "version": "0.0.1",
    "description": "Node.js module to convert FLV to MP3 files",
    "preferGlobal": "true",
    "main": "index.js",
    "bin": { "flv2mp3": "index.js" },
    "author": "Hack Sparrow ",
    "keywords": ["mp3", "flv", "converter"],
    "repository" : {
        "type": "git",
        "url": "https://hacksparrow@github.com/hacksparrow/flv2mp3.git"
    },
    "dependencies": {
        "commander": "0.5.2"
    },
    "engines": { "node": "*" }
}

The properties of the package.json file should be obvious about what their purposes are. The main property points to the JavaScript file that is the entry point of the module.

Since we'd want flv2mp3 to be used as a commandline tool, we have set "preferGlobal": "true" and "bin": { "flv2mp3": "index.js" }. If it were a library module, that would not have been required.

README.md is the 'introduction and guide file' for the project, formatted in GitHub flavored Markdown.

We then host this project on GitHub. GitHub hosting is a topic for another day, for now figure out yourself how to do that.

Our remote repository is set up. Time to configure NPM.

cd to the flv2mp3 directory and run the NPM link command:

$ npm link

If that throws npm ERR! Error: EACCES, permission denied ..., do this:

$ sudo npm link

All set, now list the files in the dir to see what changed:

-rwxr-xr-x 1 hacksparrow hacksparrow 1024 2012-02-25 22:38 index.js
drwxr-xr-x 3 hacksparrow hacksparrow 4096 2012-02-26 00:04 node_modules
-rw-rw-r-- 1 hacksparrow hacksparrow  471 2012-02-25 23:56 package.json
-rw-rw-r-- 1 hacksparrow hacksparrow 1035 2012-02-25 23:02 README.md

We have a new directory node_modules. NPM link created it as a part of dependency management, but we don't want its contents to be part of the git repository, so let's add node_modules to .gitignore.

$ echo node_modules/ >> .gitignore

You need to register with NPM to be able to publish modules on it. Call the adduser command to either create or verify your username.

$ npm adduser

Once you have completed the user adding process, call the publish command in the project directory:

$ npm publish

Congrats! You just published your first Node.js module.

Anytime you make some major changes, update the version field of package.json and execute the publish command again to update the NPM registry.

In this post we learnt how to create NPM packages and publish them on the NPM registry. I hope you contribute to the registry with a package which is actually more useful than flv2mp3. Good luck!