Plugins

Prerequisites

1. Hapi version 0.15.x or greater is installed
2. A folder with a package.json and main entry point file exist (index.js)

Please read the reference guide for an overview of creating the plugin structure.

Creating an API

A plugin always has the ability to add properties and methods to the 'api' object. This object is useful for exposing any functionality publically. This tutorial will demonstrate how to add a function and property to this object.

Export a register function that looks like the following:

exports.register = function (pack, options, next) {
    
    pack.api.hello = 'Hello';
    pack.api.world = 'World';
    pack.api.sayHello = sayHello;
    
    next();
};


function sayHello () {
  
  console.log(this.hello + ' ' + this.world);
}

In the above the 'sayHello' is called with the plugin api as the context. Therefore, it is possible to refer to the plugin api properties using 'this'. The 'sayHello' function and the other properties are also accessible under the 'server.plugins["plugin name"]' object, where "plugin name" is the name of the installed plugin to access. Below is an example of requiring the previous plugin and executing the 'sayHello' function.

var Hapi = require('hapi');
var server = new Hapi.Server(8080);

server.plugin.require('api-plugin', function (err) {

    if (!err) {
        server.start(function () {
            
            server.plugins['api-plugin'].sayHello();
        });
    }
});

After the plugin is successfully required the server is started and then the plugin api method is invoked, outputting 'Hello World' to the console.

Routing

When a pack allows the 'route' permission then any plugin within the pack can add routes to the server. In the plugin module export a 'register' function with the following signature:

exports.register = function (pack, options, next)

Next call 'route' and then call 'next'.

pack.route({ method: 'GET', path: '/', handler: function (request) {

  request.reply('Hello Plugins');
}});
next();

In the event that a pack doesn't grant the 'route' permission an exception will be thrown. Therefore, there isn't a need to check first for this function unless the plugin will work without it.

Below is what the final plugin looks like:

exports.register = function (pack, options, next) {
  
  pack.route({ method: 'GET', path: '/', handler: function (request) {

    request.reply('Hello Plugins');
  }});
  next();
};

Plugging into a Subset of Servers

The 'register' method for a plugin is passed a 'pack' object. This object has a 'select' method that returns a pack of servers that match the provided criteria. In the following, all of the servers that support TLS will be selected and a route will be added to them.

Begin by exporting the 'register' function within the module.

exports.register = function (pack, options, next)

Now call the 'select' method on 'pack' and look for the pack of servers that have the 'secure' label.

var securePack = pack.select({ label: 'secure' });

The result of calling 'select' will be a subset package of any server that match the criteria. The result will have the same methods that existed on the original 'pack' object passed in.

Before calling any of the methods on 'securePack' check to make sure that any servers were found that meet the criteria by checking 'length'.

if (!securePack.length) {
    return next(new Error('No secure servers found'));   
}

Finally add a route that is now guranteed to be applied to only servers that support TLS.

securePack.route({ method: 'GET', path: '/', handler: function (request) {

    request.reply('Hello Secure Server');
}});

The complete plugin 'register' function is shown below, including the call of 'next'.

exports.register = function (pack, options, next) {

    var securePack = pack.select({ label: 'secure' });
    if (!securePack.length) {
        return next(new Error('No secure servers found'));   
    }
    
    securePack.route({ method: 'GET', path: '/', handler: function (request) {

        request.reply('Hello Secure Server');
    }});
    
    next();
};