Getting Started with Hapi.js

hapi.js is a Node.js framework designed for building web applications and services. It allows developers to focus on writing their applications instead of spending time building infrastructure.

This tutorial assumes that you have some basic knowledge of JavaScript and Node.js. If not, checkout our Getting Started with Node.js (coming) tutorial first.

Install Node.js

Before installing hapi.js, make sure you have Node.js and npm installed:

$ node -v

$ npm -v

If you don't you can Download the package provided from the Node.js website. This is the easiest way to install both.


yarn is a new package manager that has recently gained in popularity. It's faster, more reliable, and more secure than npm.

We actually recommend using yarn, so if you aren't already, you should give it a try!

$ yarn -v

Create your Hapi project

Before you install hapi, make sure you have a project directory created:

$ mkdir hapi && cd hapi

Now, create a package.json to keep track of your application meta, and all it's dependencies. You can do this manually, but it's recommended you use the init command, which is the same for both npm and yarn:

# if you're using npm
$ npm init

# if you're using yarn
$ yarn init

Install Hapi.js

Next install hapi. Note that with npm you have to make sure to save the dependency to your package.json, yarn does this by default:

# if you're using NPM
$ npm install hapi --save

# if you're using Yarn
$ yarn add hapi


Create a server.js file at the root of your application. This is where your application code will live:

'use strict';

const Hapi = require('hapi');

// create a new server with a host and port
const server = new Hapi.Server();  
server.connection({host: 'localhost', port: 3000});

// add the route
  method: 'GET',
  handler: function (request, reply) {
    return reply('hello hapi');

// start the server
server.start((err) => {  
  if (err) {throw err;}
  console.log('Server running at:',;

This is a very simple example. A more complicated application will have more than just a server.js that houses the entire application.

Starting your application

You can now start your application with npm start or yarn start and visit it in your browser at localhost:8000/

Thats it!

Using Nanobox

I want to do a quick example using Nanobox to compare the difference in workflow, and how Nanobox can really help speed up your development.

Nanobox uses Docker to create consistent, isolated, development environments that can be deployed anywhere. If you really want to experience the full effect of the Nanobox workflow, uninstall Node, npm/yarn, and hapi.

Trust me, it's worth it...

Configure your environment

Nanobox uses a simple config file when creating application environments.

At the root of your project create a boxfile.yml and add the following:

  engine: nodejs

Now you can nanobox run. This will spin up a virtual environment and mount your code base inside. It will also install nodejs, npm, and yarn, for you so you don't have to!

You'll be dropped into a Nanobox console where you can install initialize your application and install hapi:

yarn init
yarn add hapi

You would create your application the same way as above, with one minor change. You'll need to update your server.js to listen on all available IP's. hapi actually does this by default, but it's good to define it explicitly anyway:

server.connection({host: '', port: 3000});  

You can start your application by doing either npm start or yarn start from inside the Nanobox console, or you can exit and from your command line do nanobox run yarn start.

That's it!


The coolest thing about this is, if you uninstalled everything before doing running Nanobox, you'll notice that you don't have anything installed or running on your local machine. It's all running in an isolated development environment!

No more worrying about language versions, and version managers, or having package conflicts between projects. Each application runs in it's own environment that you can share with anyone, and deploy anywhere!

What next?

Deploying a hapi.js application to production (coming soon)
Optimizing hapi.js for production (coming soon)
Managing a production hapi.js application (coming soon)

Need help?

Let us know if you have any questions, or run into any issues. We love helping you get your apps running so much that we do it for free!

You can reach us at or join our Slack team and reach out.

Posted in Hapi.js, Node.js, Getting Started, Nanobox