Hapi HTTP to HTTPS Redirection

6.0.0 · active · verified Wed Apr 22

hapi-require-https is a Hapi plugin designed to enforce HTTPS for incoming requests, providing automatic HTTP to HTTPS redirection. The current stable version is 6.0.0, which requires Hapi v20 or newer. This plugin primarily operates by default using the `X-Forwarded-Proto` header, making it ideal for applications running behind a reverse proxy (like on Heroku or other PaaS environments). It offers a straightforward API, registering as an `onRequest` lifecycle hook to perform 301 redirects. A key differentiator is its explicit support for proxy environments, configurable via a `proxy` option, which can be set to `false` to redirect based on the actual request protocol instead of the forwarded header. Release cadence typically aligns with major Hapi versions or necessary compatibility updates.

Common errors

```
Error: Plugin `@hapi/hapi` version mismatch. `@hapi/hapi` must be `~20.0.0` but `19.1.0` was found.
```
cause The installed version of Hapi does not meet the peer dependency requirements of hapi-require-https v6.0.0.

fix Upgrade your Hapi installation: `npm install @hapi/hapi@^20` or `yarn add @hapi/hapi@^20`. Alternatively, downgrade hapi-require-https to a version compatible with your current Hapi installation, e.g., `npm install hapi-require-https@^5`.
```
ERR_HTTP_HEADERS_SENT: Cannot set headers after they are sent to the client
```
cause This error typically occurs if a response has already been sent (e.g., by another plugin or route handler) before hapi-require-https attempts to issue a redirect. Ensure hapi-require-https runs early in the request lifecycle.

fix Verify the order of plugin registration. hapi-require-https should generally be registered before other plugins that might send responses or perform complex operations that could interfere with early redirection.

Warnings

breaking hapi-require-https v6.0.0 introduced a peer dependency on `@hapi/hapi` version `>=20`. Applications using older Hapi versions (e.g., v19 or earlier) must upgrade Hapi or use an older version of this plugin.
Fix: Upgrade your Hapi server to `@hapi/hapi@^20.0.0` or higher, or downgrade `hapi-require-https` to a compatible major version (e.g., `5.x` for Hapi v19).
gotcha By default, the plugin redirects based on the `X-Forwarded-Proto` header (`options.proxy` is `true`). If your application is not behind a reverse proxy that sets this header, requests will not redirect as expected, or may redirect incorrectly.
Fix: If your application is not behind a reverse proxy, set the `proxy` option to `false` when registering the plugin: `server.register({ plugin: HapiRequireHttps, options: { proxy: false } })`. This forces redirection based on the actual request protocol.
breaking The package moved towards an ESM-first approach in its distribution. While CommonJS `require()` still generally works, developers should be aware of potential import issues in mixed environments or newer Node.js versions, especially with TypeScript `moduleResolution: 'node16'` or `bundler`.
Fix: Prefer `import HapiRequireHttps from 'hapi-require-https';` for new projects or when using ESM. For existing CommonJS projects, continue using `const HapiRequireHttps = require('hapi-require-https');` but monitor for future compatibility issues.

Install

npm install hapi-require-https npm
yarn add hapi-require-https yarn
pnpm add hapi-require-https pnpm

Imports

plugin
wrong:
```
import { plugin } from 'hapi-require-https';
```
correct:
```
import HapiRequireHttps from 'hapi-require-https';
// then use HapiRequireHttps in server.register
```
The package exports the plugin object as its default export for direct registration with Hapi. Since v3, it is primarily ESM-compatible, though CJS `require` still works.

plugin (CommonJS)

wrong:

const { plugin } = require('hapi-require-https');

correct:

const HapiRequireHttps = require('hapi-require-https');
// then use HapiRequireHttps in server.register

For CommonJS environments, `require()` directly returns the plugin object, which should be passed to `server.register`.

Options type
```
import type { Options } from 'hapi-require-https';
```
Import the `Options` type for type-checking when configuring the plugin.

Quickstart

This quickstart demonstrates how to set up a basic Hapi server and register hapi-require-https, enabling automatic HTTP to HTTPS redirection. It includes a simple route to show the active protocol.

import Hapi from '@hapi/hapi';
import HapiRequireHttps from 'hapi-require-https';

const init = async () => {
    const server = Hapi.server({
        port: 3000,
        host: 'localhost'
    });

    await server.register({
        plugin: HapiRequireHttps,
        options: {
            proxy: true // Default, redirects based on X-Forwarded-Proto
        }
    });

    server.route({
        method: 'GET',
        path: '/',
        handler: (request, h) => {
            return `Hello from Hapi! Protocol: ${request.server.info.protocol}. Real protocol: ${request.headers['x-forwarded-proto'] || 'unknown'}`;
        }
    });

    await server.start();
    console.log(`Server running on ${server.info.uri}`);
};

process.on('unhandledRejection', (err) => {
    console.log(err);
    process.exit(1);
});

init();

view raw JSON →