NodeJS services with ES6: Getting Started

A few months ago I was delighted to be given the chance of building several backend REST services using NodeJS. Being a greenfield project I quickly decided to use the latest LTS version of NodeJS so that I could harness the power of ECMAScript 2015.

There were specific requirements regarding functionality but technically it came down to needing some sort of storage, integrate with OAuth2 and exposing REST services. The initial version took me 2 full weeks of development and refining. In that time frame I scoured the internet numerous times to find answers to questions regarding project setup, best practices and specific library usages. The lack of some of these things in the NodeJS landscape made me decide to create a mini-series of blog posts to elaborate how I’ve set it up.

I’ll be setting up a recipe management app using Koa, PostgreSQL with Knex and Bookshelf, Passport, Mocha, Docker and a variety of other utilities.

I’ll be gradually expanding the application to cover all these topics in a post per month. In this first article, I’ll start of with setting up the project and adding tools to easily run it and perform automatic code style checking.

All the source code is available on Github.

Setting up a NodeJS project

In order to build a NodeJS project you obviously need to install NodeJS. If you haven’t done so yet, head over to the official website and download the latest LTS version (currently 4.2.4).

After installing NodeJS start of by creating a new directory, open up your favourite terminal and run the following command from the newly created directory:

npm init

This command will guide you through adding the basics to your package.json.

If you’re going to be working with Git it’s advisable to add a .gitignore file to your project:

.idea/
node_modules/
npm-debug.log

By adding these lines 3 things will be ignored:

• The node_modules folder containing all the dependencies
• The IntelliJ IDEA configuration folder
• The NodeJS debug log file

Project structure

I like to maintain a concise and clean directory structure. I will be dividing my code into 2 directories, one for the actual production code and one for all our test code:

app/
test/
.gitignore
package.json

Our first NodeJS program

To create the simplest possible NodeJS application all you need to do is create a new Javascript file, let’s call it index.js, and let it output hello world!

console.log('hello world!');

Now how do we run this? Out of the box you have the ability to run this using the node binary on your command line

node index.js

Although this actually runs the application it will not automatically detect any changes you make to the project files forcing you to continually rerun the command after making changes.

For this there is a great package called nodemon. It will watch for any file changes in the directory where it is started and automatically restart your application. Installing nodemon can be done using the Node package manager:

npm install --save nodemon

By using — save the dependency will not only be downloaded but also added as a dependency to your package.json.

Try rerunning the application again but this time using nodemon:

nodemon index.js

Nodemon is a great utility while developing but when running in production it is advisable to use pm2 instead. pm2 does exactly what nodemon does but it offers more features which could be very useful for running in production. You can use Keymetrics.io to monitor your production instances when running pm2 and get a lot of insight into what’s going on with your application.

You’ll probably be wondering why I wouldn’t just use pm2 for local development too. The only reason I have for not doing that is that the start-up time for nodemon is lower than pm2.

Install pm2 using the following command:

npm install --save pm2

After installing pm2 you can run the application using pm2 with the following command. I’ve added the — no-daemon flag to indicate that we want to run pm2 as a foreground task. Simply omit this flag if you would like it to run in the background.

pm2 start index.js --no-daemon

To make it even easier to run our application locally and in production I’ll add 2 scripts to the package.json so that we can utilise easier to remember commands. Change the generated scripts section in your package.json to the following:

From now on you can use the following commands to run locally and in production:

npm run start-local
npm start

Consistent coding

Now that I can run my application I want to make sure that the code that I write follows the same rules at all times. Discipline and your own way of coding can do a lot to help you with this but you’re only human and are bound to make small mistakes here and there.

To solve this problem and make me more aware of the code I’m writing I’ll add a Javascript linter called eslint. If you are familiar with JSLint, this basically does the same thing but has support for ECMAScript 2015:

npm install --save-dev eslint

Since I only need eslint during development, I’ll use the — save-dev flag instead of the — save flag to indicate that I want to save eslint as a development dependency in my package.json.

Let’s also configure a helper script to make running eslint easier. Add the following line to your scripts section in the package.json:

“lint”: “eslint app/* test/*”,

Running npm run lint will scan both my source folders and output any warnings or errors in my terminal. However, manually running this command after every change still requires a lot of discipline. It’s advisable, when using a version control system like Git, to automatically run eslint using a pre-commit or pre-push hook.

I myself like to use a pre-push hook because I tend to make a lot of fine grained commits and especially when you incorporate running all your tests using the hook it will save you a lot of time waiting for test execution to be finished.

To set up the pre-push hook there are a few things I need to do. First of all, create a directory called tools in the root of your project. In this folder we will add 2 files: one for adding the pre-push hook to git and the pre-push hook itself.

The pre-push hook installation is a simple shell script (will not work on Windows) that copies the pre-push hook file to the git configuration folder (.git/):

It will look for a file called git-pre-push inside the tools folder relative from your current working directory and install it in the .git folder also relative from your current working directory.

The git-pre-push file looks as follows:

Be sure to make both files executable using the chmod command on OS X and Linux:

chmod u+x git-pre-push
chmod u+x pre-push-install

The last thing we need to do is make sure that this hook is automatically installed after running npm install. This will make it convenient for you, but also other people that will check out your project, to get started.

To do so, add the following script to the scripts section in your package.json:

“postinstall”: “./tools/pre-push-install”,

Now try running npm install and you should see a line at the end of the output saying that the hook has been installed.

Conclusion

Over the course of this article I’ve set up the basics that I need for my NodeJS service. I have a basic project that I can run in development and production and I’ve also added automatic code style checking when pushing to Git.

Overall, your package.json scripts section should now look like this:

If you’d rather get a copy of the state of the recipe manager at the end of this article, clone the getting-started tag from my repository.

Next up

Next time I’ll be adding the basic setup I need to expose REST APIs using Koa.