{"id":17245,"library":"hapi-require-https","title":"Hapi HTTP to HTTPS Redirection","description":"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.","status":"active","version":"6.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/bendrucker/hapi-require-https","tags":["javascript","hapi","https","redirect","paas","heroku"],"install":[{"cmd":"npm install hapi-require-https","lang":"bash","label":"npm"},{"cmd":"yarn add hapi-require-https","lang":"bash","label":"yarn"},{"cmd":"pnpm add hapi-require-https","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; this is a Hapi plugin and requires a compatible Hapi server instance.","package":"@hapi/hapi","optional":false}],"imports":[{"note":"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.","wrong":"import { plugin } from 'hapi-require-https';","symbol":"plugin","correct":"import HapiRequireHttps from 'hapi-require-https';\n// then use HapiRequireHttps in server.register"},{"note":"For CommonJS environments, `require()` directly returns the plugin object, which should be passed to `server.register`.","wrong":"const { plugin } = require('hapi-require-https');","symbol":"plugin (CommonJS)","correct":"const HapiRequireHttps = require('hapi-require-https');\n// then use HapiRequireHttps in server.register"},{"note":"Import the `Options` type for type-checking when configuring the plugin.","symbol":"Options type","correct":"import type { Options } from 'hapi-require-https';"}],"quickstart":{"code":"import Hapi from '@hapi/hapi';\nimport HapiRequireHttps from 'hapi-require-https';\n\nconst init = async () => {\n    const server = Hapi.server({\n        port: 3000,\n        host: 'localhost'\n    });\n\n    await server.register({\n        plugin: HapiRequireHttps,\n        options: {\n            proxy: true // Default, redirects based on X-Forwarded-Proto\n        }\n    });\n\n    server.route({\n        method: 'GET',\n        path: '/',\n        handler: (request, h) => {\n            return `Hello from Hapi! Protocol: ${request.server.info.protocol}. Real protocol: ${request.headers['x-forwarded-proto'] || 'unknown'}`;\n        }\n    });\n\n    await server.start();\n    console.log(`Server running on ${server.info.uri}`);\n};\n\nprocess.on('unhandledRejection', (err) => {\n    console.log(err);\n    process.exit(1);\n});\n\ninit();","lang":"typescript","description":"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."},"warnings":[{"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).","message":"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.","severity":"breaking","affected_versions":">=6.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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`.","severity":"breaking","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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`.","cause":"The installed version of Hapi does not meet the peer dependency requirements of hapi-require-https v6.0.0.","error":"Error: Plugin `@hapi/hapi` version mismatch. `@hapi/hapi` must be `~20.0.0` but `19.1.0` was found."},{"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.","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.","error":"ERR_HTTP_HEADERS_SENT: Cannot set headers after they are sent to the client"}],"ecosystem":"npm","meta_description":null}