{"id":17895,"library":"redirect-https","title":"HTTP to HTTPS Redirect Middleware","description":"redirect-https is a Node.js middleware designed for securing web applications by forcing HTTP traffic to HTTPS. It primarily functions by issuing a 301 (Moved Permanently) redirect for browsers while opting for an HTML meta refresh redirect for non-browser clients like APIs, bots, and `curl` requests. This deliberate choice aims to make developers aware of insecure HTTP usage, preventing silent failures often associated with direct 301s for programmatic access. The package is currently at version 1.3.1 and is a mature, stable utility with an infrequent release cadence, focusing on its core secure-by-default philosophy rather than extensive configurability. It is compatible with Express.js and standard Node.js `http` servers, offering options for custom body messages, proxy trust configuration, and specific path matching for advanced scenarios. Its key differentiator is the \"secure-by-default\" meta redirect strategy to surface security issues to developers.","status":"maintenance","version":"1.3.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","https","http","redirect","force","upgrade","location","meta"],"install":[{"cmd":"npm install redirect-https","lang":"bash","label":"npm"},{"cmd":"yarn add redirect-https","lang":"bash","label":"yarn"},{"cmd":"pnpm add redirect-https","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is a CommonJS module. The `require` call returns a function that acts as middleware when invoked with options. Direct ESM `import` is not supported without transpilation or tools like `esm`.","wrong":"import redirector from 'redirect-https';","symbol":"redirectorFactory","correct":"const redirector = require('redirect-https')({ /* options */ });"},{"note":"The module exports a function that should be called to create the actual middleware. It is not intended to be used directly without configuration.","symbol":"createRedirectMiddleware","correct":"const createRedirectMiddleware = require('redirect-https');\nconst redirector = createRedirectMiddleware({ port: 443 });"},{"note":"The generated middleware function is typically passed directly to an HTTP server's request listener or an Express.js app's `use` method.","symbol":"redirect-https middleware","correct":"app.use('/', require('redirect-https')({ trustProxy: true }));"}],"quickstart":{"code":"\"use strict\";\n\nvar http = require(\"http\");\nvar server = http.createServer();\nvar securePort = process.argv[2] || 8443;\nvar insecurePort = process.argv[3] || 8080;\n\nvar redirector = require(\"redirect-https\")({\n    port: securePort,\n    body: \"<!-- Hello! Please use HTTPS instead: {{ URL }} -->\",\n    trustProxy: true // default is false\n});\n\nserver.on(\"request\", redirector);\n\nserver.listen(insecurePort, function () {\n    console.log(\n        \"Listening on http://localhost.rootprojects.org:\" +\n            server.address().port\n    );\n});","lang":"javascript","description":"This example demonstrates how to set up `redirect-https` with a standard Node.js HTTP server, forcing redirects from an insecure port to a secure one, and configuring `trustProxy` for reverse proxy setups."},"warnings":[{"fix":"If direct 301 redirects are desired for APIs or bots, configure the `apis` option: `require('redirect-https')({ apis: 301 })`. Consider the security implications before doing so.","message":"By default, `redirect-https` uses HTML meta redirects for non-browser user agents (like `curl`, APIs, bots). This is an intentional security feature to make developers aware of insecure HTTP calls, but it will break command-line tools and programmatic API requests that expect a direct 3xx HTTP redirect.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Enable the `trustProxy` option: `require('redirect-https')({ trustProxy: true })`. This makes the middleware inspect `X-Forwarded-Proto` headers to determine the client's original protocol.","message":"When running behind a reverse proxy (e.g., Nginx, AWS ELB, Heroku) that handles TLS termination, `redirect-https` might incorrectly redirect if it doesn't know the original protocol was HTTPS. This is because the connection to Node.js itself is HTTP.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Prefer the default behavior or general options. Only use `paths` for very specific, well-understood edge cases, such as handling `curl | bash` installers that require a 301 on `/`.","message":"The `paths` option allows fine-grained control over redirects for specific paths, but the documentation advises against getting \"too fancy.\" Over-complicating redirect logic can introduce bugs or reduce maintainability.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If method-specific redirection is required, implement a custom middleware or conditional logic before `redirect-https`.","message":"The package does not support custom redirect strategies based on specific HTTP methods (e.g., only redirect GET requests). All requests to an insecure endpoint will be redirected according to the configured rules.","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":"This is often the intended behavior of `redirect-https` to highlight insecure usage. To allow `curl` to receive a 301 redirect, configure the `apis` option: `redirector = require('redirect-https')({ apis: 301 });`.","cause":"Attempts to fetch resources from an HTTP endpoint using `curl` or similar command-line tools fail unexpectedly, especially when the default meta redirect behavior is active.","error":"Error: read ECONNRESET / curl: (18) transfer closed with 0 bytes received"},{"fix":"Ensure the `trustProxy` option is set to `true` when initializing `redirect-https` to correctly interpret `X-Forwarded-Proto` headers from the proxy: `redirector = require('redirect-https')({ trustProxy: true });`.","cause":"The server isn't correctly identifying that the request originated via HTTPS, likely due to a reverse proxy (like Nginx, AWS ELB) terminating TLS and forwarding as HTTP.","error":"My application isn't redirecting to HTTPS, or it's stuck in a redirect loop when deployed behind a load balancer."},{"fix":"Always prefer `{{ URL }}` or `{{ HTML_URL }}` which are safely escaped. Avoid using `{{ UNSAFE_URL }}` in user-facing content unless you have performed your own sanitization.","cause":"While `redirect-https` performs HTML escaping, using `{{ UNSAFE_URL }}` directly in the `body` option can expose the application to cross-site scripting (XSS) vulnerabilities if the original URL contains malicious input.","error":"The `{{ URL }}` or `{{ HTML_URL }}` placeholders in the custom body are not correctly escaping special characters or are being exploited."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}