{"id":17896,"library":"redirect-ssl","title":"HTTPS Redirect Middleware","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/unjs/redirect-ssl","tags":["javascript","typescript"],"install":[{"cmd":"npm install redirect-ssl","lang":"bash","label":"npm"},{"cmd":"yarn add redirect-ssl","lang":"bash","label":"yarn"},{"cmd":"pnpm add redirect-ssl","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM named import is preferred for `redirectSSL`, but CommonJS `require` is also supported for older Node.js environments or specific build setups.","wrong":"const redirectSSL = require('redirect-ssl')","symbol":"redirectSSL","correct":"import redirectSSL from 'redirect-ssl'"},{"note":"The `create` function is a property of the default export, not a separate named export. It's used to apply custom options.","wrong":"import { create } from 'redirect-ssl'; app.use(create({ redirectPort: 8443 }))","symbol":"redirectSSL.create","correct":"import redirectSSL from 'redirect-ssl'; app.use(redirectSSL.create({ redirectPort: 8443 }))"},{"note":"The package ships with TypeScript types. `RedirectOptions` interface is available for type-checking custom configurations.","symbol":"redirectSSL Types","correct":"import redirectSSL, { RedirectOptions } from 'redirect-ssl'"}],"quickstart":{"code":"import express from 'express';\nimport redirectSSL from 'redirect-ssl';\n\nconst app = express();\nconst PORT = process.env.PORT || 3000;\nconst HTTPS_PORT = process.env.HTTPS_PORT || 8443;\n\n// Apply redirect-ssl middleware as the first middleware\n// Only enable in production and exclude localhost for development ease\napp.use(redirectSSL.create({\n  enabled: process.env.NODE_ENV === 'production',\n  exclude: ['localhost'],\n  redirectPort: HTTPS_PORT\n}));\n\napp.get('/', (req, res) => {\n  res.send('Hello from redirect-ssl example!');\n});\n\n// In a real application, you'd also have an HTTPS server listening on HTTPS_PORT\napp.listen(PORT, () => {\n  console.log(`HTTP server listening on port ${PORT}`);\n  console.log(`(HTTPS redirection target set to port ${HTTPS_PORT})`);\n  console.log('Try visiting http://localhost:3000 (will redirect in production)');\n});","lang":"typescript","description":"Demonstrates basic usage with Express, enabling HTTPS redirection only in production environments and configuring a custom HTTPS port for redirection, while excluding localhost."},"warnings":[{"fix":"Update your configuration to use `trustProxy` instead of `xForwardedProto`. The default value is `true`.","message":"The `xForwardedProto` option was renamed to `trustProxy` in `v2.0.0`.","severity":"breaking","affected_versions":">=2.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`.","message":"The `redirect` option was renamed to `enabled` and its default value is always `true` since `v2.0.0`.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Version `2.0.0` and later were rewritten in TypeScript, which might introduce subtle behavior changes for express-like frameworks or specific middleware chains.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"The middleware should be placed as early as possible in your middleware chain to ensure all requests are intercepted for HTTPS redirection.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"Setting `redirectUnknown: true` can cause redirect loops in certain environments where HTTPS detection methods are unavailable or misconfigured, particularly with load balancers or proxies.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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);`","cause":"`redirect-ssl` is an Express/Connect middleware, it requires an `app` instance from one of these frameworks.","error":"TypeError: app.use is not a function"},{"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`.","cause":"The browser is stuck in a redirect loop, often due to misconfiguration of `redirectUnknown` or incorrect `x-forwarded-proto` headers from proxies.","error":"ERR_TOO_MANY_REDIRECTS"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}