redirect-ssl

library3.0.0jsnpmunverified

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.

web-framework

npm install redirect-ssl

github ↗package ↗

INSTALL

IMPORT

SIG · REDIRECT-SSL

redirect-ssl

web-frameworkjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

redirectSSL

✓ import redirectSSL from 'redirect-ssl'

✗ const redirectSSL = require('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

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

✗ import { create } from 'redirect-ssl'; app.use(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.

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)'); });

Debug

Known issues

breakingThe `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`.

affects: >=2.0.0

breakingThe `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`.

affects: >=2.0.0

breakingVersion `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.

affects: >=2.0.0

gotchaThe 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.

affects: >=1.0.0

gotchaSetting `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`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: app.use is not a function

`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);`

ERR_TOO_MANY_REDIRECTS

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`.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/unjs/redirect-ssl ↗

packagehttps://www.npmjs.com/package/redirect-ssl ↗