Inert

To use @hapi/inert for serving static files, you must first register it with your Hapi server. Once registered, it provides the h.file() method on the response toolkit and exposes 'file' and 'directory' handlers for your routes.

const Hapi = require('@hapi/hapi');
const Inert = require('@hapi/inert');

const server = new Hapi.Server({
    port: 3000,
    routes: {
        files: {
            relativeTo: Path.join(__dirname, 'public')
        }
    }
});

const provision = async () => {
    await server.register(Inert);
    // ... setup routes
    await server.start();
};

provision();

You can configure @hapi/inert via the plugins.inert key in your Hapi server configuration.

• etagsCacheMaxSize (number): Sets the maximum number of file etag hash values stored in the cache. Defaults to 1000.

To use Inert in your hapi server, register it as a plugin. Inert does not support registration options; the options object passed to register must be empty. It requires hapi version >=20.0.0.

await server.register({
    plugin: require('@hapi/inert'),
    options: {}
});

Inert uses Boom to signal file access errors:

• Boom.notFound(): For missing or hidden files.
• Boom.forbidden(): For files that exist but cannot be accessed.
• Boom.internal() / 'system': For unexpected configuration or processing errors.

Errors may contain an err.data.path property indicating the path that failed.

The file handler is used in a route configuration to serve a specific file. The path can be a string (relative to the route's files.relativeTo config) or a function that returns the path.

server.route({
    method: 'GET',
    path: '/{path*}',
    handler: {
        file: 'page.html'
    }
});

The directory handler allows you to serve an entire folder. Routes using this handler must include a path parameter at the end of the path string (e.g., /{param*}).

Common options for the directory handler:

• path: The directory root (string, array of strings, or a function returning them).
• index: If true, looks for index.html. Can be a specific string or array of strings.
• redirectToSlash: Redirects requests for a directory without a trailing slash to the version with a slash.
• listing: Enables directory listing if no index file is found.

server.route({
    method: 'GET',
    path: '/{param*}',
    handler: {
        directory: {
            path: '.',
            redirectToSlash: true,
            index: true,
        }
    }
});

Inside a route handler, you can use h.file(path, [options]) to respond with a file. This is useful for dynamic file selection based on request logic or error handling.

server.route({
    method: 'GET',
    path: '/file',
    handler(request, h) {
        let path = 'plain.txt';
        if (request.headers['x-magic'] === 'sekret') {
            path = 'awesome.png';
        }

        return h.file(path).vary('x-magic');
    }
});

// Example: Custom 404 page
server.ext('onPreResponse', (request, h) => {
    const response = request.response;
    if (response.isBoom && response.output.statusCode === 404) {
        return h.file('404.html').code(404);
    }
    return h.continue;
});

You can configure the maximum size of the ETag cache via the server's plugin settings. This is done by providing an inert object within your server configuration. The etagsCacheMaxSize option must be a non-negative integer (defaults to 1000 if not specified).

const server = Hapi.server({
    // ... other server settings
    plugins: {
        inert: {
            etagsCacheMaxSize: 500
        }
    }
});

Inert decorates the hapi toolkit (the h object) with a file method. This is useful when you want to return a file response from within a handler using the toolkit.

Key options for h.file(path, responseOptions):

• confine: A string defining the directory boundary. Defaults to '.' if undefined or true. This prevents access to files outside the specified directory.
• start: The byte offset to start reading from.
• end: The byte offset to stop reading at.

Note: options.start must be less than or equal to options.end.

server.route({
    method: 'GET',
    path: '/download',
    handler: (request, h) => {
        return h.file('/path/to/file.zip', {
            start: 0,
            end: 1024
        });
    }
});