Vision for hapi.js

If a templating engine does not follow the standard API pattern, you can map it to the Vision API by providing a compile function (and optionally a prepare function) within the engines configuration object.

The compile function

The compile function receives the source (src) and options. It must return a function that accepts a context object and returns the rendered string.

The prepare function

The prepare function is used to perform setup tasks (like configuring an environment) before compilation. It receives options and a next callback.

// Example: Mapping Mustache to the Vision API
server.views({
    engines: {
        html: {
            compile: (template) => {
                Mustache.parse(template);
                return (context) => {
                    return Mustache.render(template, context);
                };
            }
        }
    }
});

To enable autocompletion and type safety for templates and layouts, you can augment the @hapi/vision module.

Typing the Response Handler

Define ViewTypes to restrict template and layout to your specific filenames.

Typing Decorated Handlers

To provide strict type checking for server.render, request.render, and h.view, augment the following interfaces:

• RenderMethod (for server.render)
• RequestRenderMethod (for request.render)
• ToolkitRenderMethod (for h.view)

You can even define specific context shapes for specific templates to ensure strict type safety across your views.

declare module '@hapi/vision' {
    // User defined template names
    type CustomTemplates = 'test' | 'hello' | 'temp1';

    // User defined layout names
    type CustomLayout = 'auth' | 'unauth' | 'admin';

    interface ViewTypes {
        template: CustomTemplates
        layout: CustomLayout
    }

    // Typing the toolkit h.view()
    interface ToolkitRenderMethod {
        (template: 'test', context: { apples: number }): ResponseObject;
        (template: 'hello', context: { oranges: boolean }): ResponseObject;
    }
}

When initializing the view manager via server.views(options), you can provide a configuration object to control how templates are resolved, rendered, and cached.

Key configuration options include:

• engines: A required object mapping file extensions (e.g., 'html', 'hbr') to npm modules. You can also map an extension to an object containing a module and optional methods like prepare(), registerPartial(), or registerHelper().
• path: The root directory for templates. Defaults to the current working directory.
• partialsPath: The directory for reusable template segments.
• helpersPath: The directory for helper functions. Files in this directory must export a single function with the signature function(context) that returns a string.
• layout: Enables layout support. If set to a filename, that file acts as the parent template.
• layoutPath: The directory for layout templates. Defaults to path.
• layoutKeyword: The key used by the engine to denote where primary content is injected. Defaults to 'content'.
• isCached: Determines if templates are cached. Defaults to true.
• context: A global context object or function (can be async) applied to all templates. When using the view handler, the function receives the request object.

The Manager class is responsible for registering template engines, managing partials, helpers, and rendering templates. When instantiating the Manager, you must provide an engines object where keys are file extensions and values are engine configurations.

Default Options

• compileOptions: Object passed to the engine's compile function.
• runtimeOptions: Object passed to the engine's render function.
• layout: Boolean or string. If true, uses a default layout template. If a string, uses that specific template as the layout.
• layoutKeyword: The key in the context used to inject the rendered content into the layout (defaults to 'content').
• encoding: File encoding (defaults to 'utf8').
• isCached: Boolean. If true, compiled templates are cached (defaults to true).
• allowAbsolutePaths: Boolean. If false, absolute paths are rejected (defaults to false).
• allowInsecureAccess: Boolean. If false, paths containing ../ are rejected (defaults to false).
• contentType: The Content-Type header for the response (defaults to 'text/html').
• compileMode: 'sync' or 'async' (defaults to 'sync').
• context: An object or a function (request) => context that provides base data for all renders.

const Manager = require('./lib/manager');

const manager = new Manager(server, {
    engines: {
        pug: {
            module: require('pug'),
            compile: (str, opt) => require('pug').compile(str, opt)
        }
    },
    defaultExtension: 'pug',
    path: '/views',
    isCached: true
});