How to write Node.js modules

In this post, I will describe a process of creating and publishing Node.js module. We will go through complete process, from initial configuration to module publishing and updating. As usual, complete source code can be found on Github.

For this project, you will need to have Node.js and NPM installed. For download and installation instructions for your system, please see official site.

Project initialization

To keep things simple, we will create a module which will simply show current time in format yyyy-MM-dd HH:mm:ss. Despite this simplicity, this module has all the aspects required for fully functional Node.js module. We will call our module curtimemod.

To begin, first create a folder named curtimemod . This will be the root of our module. Change to this directory, and run  npm init  command. This command is a CLI-style wizard which will help you initialize your module by collecting some required information. Next section shows command output and choice I made for module data:

Required entries and their default values are shown with braces, eg. name: (curtimemod) . If you do not enter anything, default values will be accepted. Here, I have skipped some entries, like test command . You can add any entry later if needed.

After wizard is completed, it will generate a file called package.json . This file contains all the data we entered in the wizard. If we later want to add or change some settings, we can simply edit this file.

Coding the module

Each Node.js module must contain an entry point. You can think of this as the main function for the module. Since we have specified our entry point to be index.js , we need to create that file. Add the following code to it:

In this code, we simply create an object called themodule , and add a function to it. The last line is what makes this file a Node.js module. Behind the scenes, this line wraps our object into Node.js infrastructure, so it can be used in other modules.

Alternative approach

Another way to code a module is to define a function directly in export statement, like this:

Personally, I find this approach useful for really simple modules, but for anything more complicated, I prefer the first approach.

Testing and debugging

Node.js provide extremely simple and useful REPL (Read Eval Print Loop) which we can use to test the module. This simple code snippet shows it:

Here, we start a Node.js runtime and load our module. Then, we can use the mod  object to invoke our module’s function.

Adding dependencies

Since this module is extremely simple, it does not need any external libraries. In most cases, you will need some more functionality which can be found in other modules. To declare a dependency to another module, we use NPM package manager. For example, we want to color our module output, so we will declare a dependency on colors  module:

This will install module in our local directory and save dependency information to package.json . Now we can use this module in our module:

This time, output is printed in red and underlined.

Publishing your module

Now we have our module completely ready, so it’s time to publish it to NPM. We will go through the entire process, but for reference, you can find more details in official documentation.

Prepare NPM user

In order to publish your module, you need to have account in NPM network. If you don’t have it, you can easily create it by running

If you already have an account, you can log in by running

Prepare the code

Node.js modules are actually code repositories which must be made available for other users, in order to be used. That is why each node module must include a repository setting in it’s package.json . Also, modules must be versioned according to semantic versioning scheme. So, since we have our git repository ready, we just need to set up the version and publish the module.

In the first line,  command npm version  created git tag called 1.0.0 . After that, we push changes to git and publish the module. If everything goes OK, you should see your new module in NPM in not time!

How to update module

Inevitably, your module will change over time. When you want to publish your modifications, you will need to update the version. Depending on scope of changes, you may want to create major, minor or patch version:

Here, npm version  will create new tag corresponding to change scope. After that, we push changes to git and publish new version

Conslusion

Congratulations, you’ve just created your first Node.js module! You can now consider yourself hard-core Node developer :-).

Seriously, you can see that there’s nothing complicated in Node modules. The main problem you might face when working with Node is that everything should be asynchronous. It may take some time for beginners to wrap their head around it, but with practice, it becomes easier.

Stay tuned for more Node.js related blog posts!

Leave a Reply

Your email address will not be published. Required fields are marked *