Starting with NPM

Let's create our first Node.js module

NPM is the package manager of Node.js and all packages are stored in a public registry : But to find one, use the website NodeJs introduced this manager since version 0.6.3. It manage dependencies and other configurations trough a package.json file. Today, there is a least 560K+ packages : that's a lot!

You also can store packages in private NPM registry : useful inside enterprises.


In order to use NPM, we need to install Node.js if not already done.

You can sudo apt-get install nodejs nodejs-dev nodejs-legacy on Ubuntu, or download Node.js.

search in the registry

You may want a package to do some stuff

look first in the registry, someone probably worked on that.

Go to find a package on

If not, find a name for your package and check if it is already taken :

$ npm view my-package
npm ERR! 404 Registry returned 404 for GET on

If npm displays a 404 error, the package does not exists, you can create it.

create your repository

Before creating the package, start to create a repository on github or other repository manager. Then, clone it in your working directory :

$ mkdir my-first-npm-package
$ cd my-first-npm-package
$ git clone

First script with node

You can execute a javascript file using node like this :

$ node index.js
simple-node-package started

where index.js contains :

console.log('simple-node-package started');

As we can see, the message simple-node-package started is logged. So, use this way to create a script that do something right now. Imagine :

$ node display-the-date.js

where display-the-date.js contains :

console.log(new Date());

Now execute the script using the Node.js REPL.

Its a Javascript prompt called REPL for Read Eval Print Loop.

It works in a way like your browser javascript console does but with node features. The most important thing to know is the import of your module with require('./file.js'). It loads your javascript file. Just do :

$ node
> var module = require('./index.js');
simple-node-package started

The same log message is displayed.

Use CTRL+C twice to exit REPL

(exit before try again if you change your script).

Be careful : require is a function that will load synchronously the indicated module.

Once the first load is done, it will cache the script, so if we load it a second time, it is not re-loaded :

> var module = require('./index.js');
simple-node-package started
> var module = require('./index.js');

Depending your code, you may have some side effects if you code wrong.

Exporting some stuff

Now there is a magic keyword with node : module.exports or exports. It permit to exports whatever you want, like literal, object, function, ... Try with index.js:

module.exports = 'myExport';

And import it:

$ node
> var module = require('./index.js');
simple-node-package started
> module

Here module equals 'myExport' string.

Now imagine exporting a function :

module.exports = function(moduleArgument) {
console.log('moduleArgument is', moduleArgument);
return 'moduleResult';

And try it :

$ node
> var module = require('./index.js');
simple-node-package started
> module

We can see that module is a (our) function and if we execute it with an argument 'moduleParameter':

> module('moduleParameter')
moduleArgument is moduleParameter

There is a log message that indicates our first argument and the returned value 'moduleResult'

More useful script

Now we will export something more useful : a module with some utility functions, an addition and multiplication functions. We start with our index.js file :

module.exports = function (coefficient) {
// no coefficient means coefficient of 1
if (!coefficient && coefficient !== 0) {
coefficient = 1;
console.log('moduleArgument coefficient is', coefficient);
this.coefficient = coefficient;
return {
addition: addition.bind(this),
multiplication: multiplication.bind(this)
function addition(x, y) {
return this.coefficient * (x + y);
function multiplication(x, y) {
return this.coefficient * x * y;

Here the function used for the module return an object of functions :

addition: addition.bind(this),
multiplication: multiplication.bind(this)

So when after importing our module with the coefficient parameter, you can call addition or multiplication functions.

Let’s try to use it :

> var module = require('./index.js');
simple-node-package started
> module().addition(1,1)
moduleArgument coefficient is 1
> module(2).addition(1,1)
moduleArgument coefficient is 2
> var coef4 = module(4)
moduleArgument coefficient is 4
> coef4.multiplication(2,2)

Finally, our module parameter coefficient is useful for our entire module and we benefit of these two functions you can use elsewhere, even in another NPM module.

create a package

We are now ready to create the package with npm init. Don't forget to add a : it will appears on the NPM registry to describe the package. It will ask a couple of questions as the package name, version, description, author, keywords and repository :

$ npm init
This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.

See `npm help json` for definitive documentation on these fields
and exactly what they do.

Use `npm install <pkg> --save` afterwards to install a package and
save it as a dependency in the package.json file.

Press ^C at any time to quit.
name: (simple-node-package) simple-node-package
version: (1.0.0) 0.0.0
description: simple node module with an addition and a multiplication methods
entry point: (index.js)
test command:
git repository: (
keywords: addition, multiplication
author: **@**
license: (ISC) MIT
About to write to C:\git\github\kirakishin\simple-node-package\package.json:

"name": "simple-node-package",
"version": "0.0.0",
"description": "simple node module with an addition and a multiplication methods",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
"repository": {
"type": "git",
"url": "git+"
"keywords": [
"author": "**@**",
"license": "MIT",
"bugs": {
"url": ""
"homepage": ""

Is this ok? (yes) yes

Once finished, the package.json file is created. You can edit it by changing the name or adding some tests.

Now take our previous script display-the-date.js:

$ node display-the-date.js

So, you can execute it through a NPM script by adding a start script in package.json :

"scripts": {
"start": "node display-the-date.js"

And try :

$ npm start
> simple-node-package@0.0.0 start /home/kirakishin/simple-node-package
> node display-the-date.js

publish your package

If you never used the NPM public registry, you must add your account :

$ npm adduser <USER>

Now add new files and commit it :

$ git add index.js package.json display-the-date.js
$ git commit -a -m "chore(init): first init"
$ npm version minor
$ git push && git push --tags

Then publish your package on the registry :

npm publish

that’s all !

Few words

In an open source World, check first if anyone already done the thing you want. If not, do it and share!

We saw how to create a node module, use it, and publish it:

  • NPM is a package manager and comes with Node.js
  • is the NPM website to find packages in the NPM registry
  • is the NPM registry where packages are stored
  • you also can use a private NPM registry inside your organization
  • start a node script with node script.js
  • exports things from your module with module.exports = 'exportedThing'
  • use REPL from node to send commands like console.log('hello')
  • use var module = require('./index.js') to import the module from index.js
  • then use it with var ask = module(42); var response = ask.bigQuestion('all')
  • and see the answer to everything in the universe

On github :
Package on NPM :

see more