HTTPS Redirect Middleware

3.0.0 verified Thu Apr 23 auth: no javascript

redirect-ssl is a Connect/Express middleware designed to enforce HTTPS for web applications, ensuring all incoming HTTP requests are redirected to their HTTPS equivalent. It leverages the `is-https` package for robust HTTPS detection, including support for `x-forwarded-proto` headers often found when deployed behind proxies. The current stable version is 3.0.0, which introduced significant changes like a TypeScript rewrite and renaming of key configuration options. While no strict release cadence is stated, major versions appear to introduce breaking changes, signaling active development and modernization. Its key differentiators include flexible configuration for proxy trust, custom redirect ports/hosts, and exclusion patterns, making it adaptable for various deployment scenarios including Nuxt.js applications. It aims to provide a reliable and configurable solution for ensuring secure communication by default.

Common errors

error TypeError: app.use is not a function ↓

cause `redirect-ssl` is an Express/Connect middleware, it requires an `app` instance from one of these frameworks.

fix

Ensure you are using redirect-ssl within an Express or Connect application, for example: import express from 'express'; const app = express(); app.use(redirectSSL);

error ERR_TOO_MANY_REDIRECTS ↓

cause The browser is stuck in a redirect loop, often due to misconfiguration of `redirectUnknown` or incorrect `x-forwarded-proto` headers from proxies.

fix

Set redirectUnknown: false in redirectSSL.create() options. If behind a proxy, ensure trustProxy: true is set and the proxy correctly forwards x-forwarded-proto.

Warnings

breaking The `xForwardedProto` option was renamed to `trustProxy` in `v2.0.0`. ↓

fix Update your configuration to use `trustProxy` instead of `xForwardedProto`. The default value is `true`.

breaking The `redirect` option was renamed to `enabled` and its default value is always `true` since `v2.0.0`. ↓

fix Replace `redirect: false` with `enabled: false`. If you relied on a default of `false`, you now explicitly need to set `enabled: false`.

breaking Version `2.0.0` and later were rewritten in TypeScript, which might introduce subtle behavior changes for express-like frameworks or specific middleware chains. ↓

fix Thoroughly test your application's redirect behavior after upgrading. Pay close attention to how `redirect-ssl` interacts with other middleware, especially those affecting request headers or response status codes.

gotcha The middleware should be placed as early as possible in your middleware chain to ensure all requests are intercepted for HTTPS redirection. ↓

fix Ensure `app.use(redirectSSL)` or `app.use(redirectSSL.create(...))` is called before any other routes or middleware that you intend to secure with HTTPS.

gotcha Setting `redirectUnknown: true` can cause redirect loops in certain environments where HTTPS detection methods are unavailable or misconfigured, particularly with load balancers or proxies. ↓

fix If you experience redirect loops, try setting `redirectUnknown: false` in your options. Additionally, verify your proxy/load balancer is correctly setting `x-forwarded-proto` headers if `trustProxy` is `true`.

Install

npm install redirect-ssl

yarn add redirect-ssl

pnpm add redirect-ssl

Imports

redirectSSL
wrong
```
const redirectSSL = require('redirect-ssl')
```
correct
```
import redirectSSL from 'redirect-ssl'
```
ESM named import is preferred for `redirectSSL`, but CommonJS `require` is also supported for older Node.js environments or specific build setups.

redirectSSL.create

wrong

import { create } from 'redirect-ssl'; app.use(create({ redirectPort: 8443 }))

correct

import redirectSSL from 'redirect-ssl'; app.use(redirectSSL.create({ redirectPort: 8443 }))

The `create` function is a property of the default export, not a separate named export. It's used to apply custom options.

redirectSSL Types
```
import redirectSSL, { RedirectOptions } from 'redirect-ssl'
```
The package ships with TypeScript types. `RedirectOptions` interface is available for type-checking custom configurations.

Quickstart

Demonstrates basic usage with Express, enabling HTTPS redirection only in production environments and configuring a custom HTTPS port for redirection, while excluding localhost.

import express from 'express';
import redirectSSL from 'redirect-ssl';

const app = express();
const PORT = process.env.PORT || 3000;
const HTTPS_PORT = process.env.HTTPS_PORT || 8443;

// Apply redirect-ssl middleware as the first middleware
// Only enable in production and exclude localhost for development ease
app.use(redirectSSL.create({
  enabled: process.env.NODE_ENV === 'production',
  exclude: ['localhost'],
  redirectPort: HTTPS_PORT
}));

app.get('/', (req, res) => {
  res.send('Hello from redirect-ssl example!');
});

// In a real application, you'd also have an HTTPS server listening on HTTPS_PORT
app.listen(PORT, () => {
  console.log(`HTTP server listening on port ${PORT}`);
  console.log(`(HTTPS redirection target set to port ${HTTPS_PORT})`);
  console.log('Try visiting http://localhost:3000 (will redirect in production)');
});