Next.js SSL Redirect Middleware

0.1.5 verified Thu Apr 23 auth: no javascript

This package provides a simple Next.js middleware to automatically redirect HTTP requests to HTTPS, primarily useful for hosting environments like Heroku that do not offer native 'force SSL' functionality out of the box. It leverages Next.js's middleware system to intercept incoming requests and issue a 301 (or configurable) redirect when the `x-forwarded-proto` header indicates an HTTP connection. The current stable version is 0.1.5. As a focused utility, it likely has a low release cadence, receiving updates mainly for critical bug fixes or compatibility with new Next.js versions. Its key differentiator is its simplicity and direct integration into the Next.js middleware architecture, offering a lightweight solution without complex server-side configurations. It aims to solve a specific problem for specific hosting providers.

Common errors

error TypeError: Cannot read properties of undefined (reading 'headers') ↓

cause The middleware is attempting to access `request.headers` but the `request` object provided to the middleware might be undefined, null, or not a valid `NextRequest` instance due to an incorrect middleware setup or Next.js version incompatibility.

fix

Ensure middleware.ts (or .js) is correctly placed at the root of your Next.js project and that your Next.js version is compatible with the middleware API being used. Verify the file is recognized by Next.js.

error ERR_TOO_MANY_REDIRECTS ↓

cause The browser is reporting too many redirects, indicating an infinite redirect loop. This often happens if the `x-forwarded-proto` header is not correctly updated to `https` after the initial redirect, or if another SSL enforcement mechanism is conflicting with this middleware.

fix

Verify that your hosting environment (e.g., load balancer, proxy) correctly sets x-forwarded-proto to https for requests that have already been redirected. Check for other server-side or CDN-level SSL configurations that might be interfering. Ensure the environments option is configured correctly and not causing redirects in an already secure context.

error Module not found: Can't resolve 'next-ssl-redirect-middleware' ↓

cause The `next-ssl-redirect-middleware` package has not been installed, or there is a typo in the import path.

fix

Run npm install next-ssl-redirect-middleware or yarn add next-ssl-redirect-middleware in your project's root directory. Double-check that the import statement import sslRedirect from 'next-ssl-redirect-middleware'; is exactly correct.

Warnings

breaking Changes to Next.js's Middleware API or underlying request/response objects could potentially break the functionality of this package without a corresponding update. Always test after Next.js major version upgrades. ↓

fix Consult the Next.js migration guide for middleware and check for an updated version of `next-ssl-redirect-middleware`. Consider pinning your Next.js version to avoid unexpected breakages.

gotcha By default, the middleware only runs in `production` environments. If testing in other environments (e.g., 'staging') or if your hosting provider uses a different `NODE_ENV` for production, you must explicitly configure the `environments` option. ↓

fix Pass an `environments` array to `sslRedirect` with all desired `NODE_ENV` values, e.g., `sslRedirect({ environments: ['production', 'staging'] })`.

gotcha Using this middleware in conjunction with server-level SSL enforcement (e.g., Vercel's automatic HTTPS, CDN rules, or reverse proxy settings) can lead to unnecessary double redirects, performance degradation, or redirect loops. This middleware is specifically for environments without native force SSL. ↓

fix Only enable this middleware if your hosting environment explicitly requires it (e.g., certain Heroku setups, custom Node.js servers). Disable it if your platform (like Vercel or Netlify) provides automatic HTTPS enforcement.

gotcha The middleware relies on the `x-forwarded-proto` header to determine the request protocol. If your proxy or load balancer does not correctly set or forward this header (or sets it incorrectly), the redirect logic may fail, leading to either no redirect or an infinite redirect loop. ↓

fix Ensure your hosting provider's proxy or load balancer correctly sets and forwards the `x-forwarded-proto` header (e.g., `x-forwarded-proto: http` or `x-forwarded-proto: https`). Consult your hosting provider's documentation.

Install

npm install next-ssl-redirect-middleware

yarn add next-ssl-redirect-middleware

pnpm add next-ssl-redirect-middleware

Imports

sslRedirect
wrong
```
const sslRedirect = require('next-ssl-redirect-middleware');
```
correct
```
import sslRedirect from 'next-ssl-redirect-middleware';
```
This library is designed for ES module imports within Next.js middleware. While CommonJS might technically work with transpilation, ESM is the intended and idiomatic approach. Type definitions are included for TypeScript users.

Quickstart

This code sets up the SSL redirect middleware to force HTTPS on 'production' and 'staging' environments with a 302 temporary redirect.

// In middleware.ts (or .js) at the root of your Next.js project
import sslRedirect from 'next-ssl-redirect-middleware';

export default sslRedirect({
  // Optional: Specify environments where the redirect should run.
  // Defaults to ['production'].
  environments: ['production', 'staging'],
  // Optional: Set the HTTP status code for the redirect.
  // Defaults to 301 (Moved Permanently).
  status: 302 // Temporarily Moved
});