Upgrading plugins to hapi 6.0 (preview)

[hueniverse]

Version 6.0.0 is a major cleanup of the plugin registration engine. In most cases, plugins can be easily upgraded to work with hapi 6.x as well as older versions. This guide provides simple instructions for getting your plugin ready today.

Note that until version 6.0.0 is published, you should not migrate your tests to the new code (due to the way most plugin are tested, the test code is very much version specific).

The biggest change is that version 6.0.0 no longer requires plugins for you. You have to call node's require() first and then pass the result back to hapi. This means that hapi no longer has access to the plugin's package.json file or to the plugin's path.

Instruction

Exports package.json

Backwards compatible change

In your plugin module, add the attributes property to the exports.register() function:

exports.register = function (plugin, options, next) {
    plugin.route({
        method: 'GET',
        path: '/',
        handler: function (request, reply) { reply('ok'); }
    });

    next()
};

exports.register.attributes = {
    pkg: require('../package.json')
};

This will export the plugin's name and version to the registration engine.

Require view engine modules directly

Backwards compatible change

When configuring view engines, call node's require() and pass the object in the configuration instead of the module name. For example, the value { html: 'handlebars' } in previous versions must now be replaced with { html: require('handlebars') }.

Adjust static resources paths

Backwards compatible when using absolute paths

In previous versions, hapi figured out where the plugin was loaded from and prefixed all relative paths (file, directory, and views) with that location. It also provided that location via the plugin.path property.

In version 6.0.0, all plugin paths must be absolute, relative to process.cwd(), or relative to a manually configured path using the new plugin.path(path) method. Note that since plugin.path() is not backwards compatible, if you want to keep the plugin working with previous versions, switch your path to absolute using __dirname instead of setting the path with plugin.path().

If you plugin uses views, file handlers, or directory handlers, review your configuration for relative paths. In general, the following will work for most plugins:

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

    plugin.path(Path.join(__dirname, '..'));

    var views = {
        engines: { 'html': require('handlebars') },
        path: './templates'
    };

    plugin.views(views);

    plugin.route({
        path: '/file', method: 'GET', handler: { file: './static/test.html' }
    }]);

    return next();
};

exports.register.attributes = {
    pkg: require('../package.json')
};

Remove plugin.loader()

Backwards compatible when loading view engines directly

The plugin.loader() method is no longer needed because view engines and other plugins are required outside of the framework. Simply remove this unused code.

Replace plugin.require() with plugin.register()

Not backwards compatible

If your plugin requires another plugin, that code has to change to use the new plugin.register() method.

Without options:

// Previous versions
plugin.require('name', function (err) {});

// Version 6.0.0
plugin.register(require('name'), function (err) {});

With options:

// Previous versions
plugin.require('name', { some: 'options' }, function (err) {});

// Version 6.0.0
plugin.register({
    plugin: require('name'),
    options: { some: 'options' }
}, function (err) {});

[lock]

This thread has been automatically locked due to inactivity. Please open a new issue for related bugs or questions following the new issue template instructions.