Mount your express app onto your hapi server, aw heck!

Lead Maintainer - Devin Ivy

See also the API Reference

Hecks is intended for use with hapi v19+ and nodejs v12+ (see v2 for lower support).

Hecks allows you to seamlessly incorporate express applications into a hapi v17+ server. This is particularly useful for testing an express server using server.inject(), for unifying deployment of existing express and hapi applications, and as an initial stepping stone in migrating an express application to hapi.

const Express = require('express');
const BodyParser = require('body-parser');
const Hapi = require('@hapi/hapi');
const Hecks = require('@hapipal/hecks');

(async () => {

    const app = Express();

    app.post('/user', BodyParser.json(), (req, res) => {

        const user = { ...req.body };
        user.saved = true;

        res.json(user);
    });

    const server = Hapi.server();

    await server.register([
        Hecks.toPlugin(app, 'my-express-app')
    ]);

    const { result } = await server.inject({
        method: 'post',
        url: '/user',
        payload: { name: 'Bill', faveFood: 'cactus' }
    });

    console.log(result); // {"name":"Bill","faveFood":"cactus","saved":true}
})();

Mount your express app onto your hapi server, aw heck!

Note

Hecks is intended for use with hapi v19+ and nodejs v12+ (see v2 for lower support).

You should register Hecks in any plugin that would like to take advantage of its features; it does not take any options. Hecks specifies the once plugin attribute, which means hapi will ensure it is not registered multiple times to the same connection.

The express handler type mounts an express application to a route. Its configuration may be either an express application or an object,

• app - an express application.
• express - (optional) the express module used to create app. In the absence of this configuration option express is simply require('express')'d as a peer dependency.

The route will automatically have the following route configuration defaults, in particular to avoid reading the request payload before express and to avoid parsing cookies aimed at the express application.

{
    payload: {
        parse: false,
        output: 'stream'
    },
    state: {
        parse: false
    }
}

The route's path has some say in determining the url passed-along to the express application. There are two possibilities,

• The route's path has a parameter named expressPath, e.g. /my-app/{expressPath*}. In this case, the url handed to the express app will have the path contained in request.params.expressPath.
• The route's path does not have a parameter named expressPath, e.g. /dogs/{id}. In this case, the url handed to the express app will be the entire path matched by the route.

In both cases, any route prefixes passed during plugin registration will be hidden from the express app. Additionally, any calls to request.setUrl() will be respected by the application.

// Serving an express app mounted at /old-api and secured behind hapi auth

server.route({
    method: '*',
    path: '/old-api/{expressPath*}',
    options: {
        auth: 'my-strategy',
        handler: { express: app } // app is an express application
    }
});

Returns a hapi plugin that mounts an express application app, with a route matching any method and path. When nameOrAttributes is a string, it will be used as the name in the plugin's attributes. If nameOrAttributes is an object, it will be used as the plugin's full attributes.