I am Hack Sparrow
Captain of the Internets.

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!

7 Responses to “Create NPM Package – Node.js Module”

  1. Kevin Kaland says:

    Thank you, kind sir. You helped me get https://npmjs.org/package/habitrpg-todo-sync published. I thought publishing on NPM would be kinda hard, but it was actually almost ridiculously easily, and all from the command line.

    Read your other post about developing CLI apps as well and put it to good use.

  2. Captain says:

    Great to hear that, Kevin.

  3. Kirby says:

    1. google “make npm package”
    2. scroll through a few “introductory” blog posts with lengthy discussions of advanced or irrelevant details
    3. find a hacksparrow post
    4. experience relief
    5. understand

    Thanks for the focused content!

  4. Anubhav says:

    It was a breezer. Thanks

  5. Atul patel says:

    Thanks for this post , Go ahead with new one like this. Good luck.

  6. Massimo says:

    Thank you so much! I would like to find thousands of this very essential, practical and easy to understand articles on JavaScript, Node.js, etc. Keep posting such good micro-tutorials please!

  7. Captain says:

    Great to know you guys love this post!

Make a Comment