When it comes to redirects, it's easy to end up with a redirect chain. First your server forces HTTPS. Redirects to the naked domain. Then removes the trailing slash. And only then does the request hit your backend, where it is met with redirects dependent on your business logic. Clean Redirect is a middleware for Express that helps you avoid redirect chains by keeping all of the redirect rules in one place, redirecting only once they've all been applied.

While it may be desirable to keep some of those redirects (such as force HTTPS) on the web server, there are cases when they need to happen on the backend, such as when hosting an application on Heroku or similar infrastructure.

:zap:   Features

• Enforce HTTPS.
• Redirect from naked domain to WWW and vice versa.
• Remove trailing slash from path.
• Convert path to lowercase.
• The ability to pass in a function with your own business logic.
• A lot of configurable options to keep it as simple or governed as you need it.

:floppy_disk:   Installation

Using NPM:

npm install --save clean-redirect

Using Yarn:

yarn add clean-redirect

:mag:   Example

const express = require('express');
const cleanRedirect = require('clean-redirect');

const app = express();

const getCustomRedirectLocation = (req, res, redirector) => {
  if (redirector.path === '/store') {
    redirector
      .setPath('/marketplace')
      .setPersistQueryString(false)
      .setRedirectCode(302);
  }
};

const redirector = cleanRedirect({
  forceHttps: true,
  toWww: true,
  pathToLowerCase: true,
  removeTrailingSlash: true,
  persistQueryString: true,
  customRedirects: getCustomRedirectLocation,
  callNextOnRedirect: true,
  redirectCode: 301,
});

app.use(redirector);

// http://yourapp.com/SUBSCRIBE/[email protected] => 301
// https://www.yourapp.com/[email protected]

// http://yourapp.com/STORE/?showBundles=true => 302
// https://www.yourapp.com/marketplace

:space_invader:   Usage

Clean Redirect exposes a single middleware function that accepts multiple options, some of which are used to configure the redirect logic, others which are used to govern the behavior of the middleware.

Options

| Option | Type | Required | Description | |-----------------------|----------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | forceHttps | Boolean | No | Redirects non-secure HTTP requests to HTTPS. Defaults to false. | | toWww | Boolean | No | Redirects requests to the naked (root) domain to the WWW domain. Defaults to false. Both toWww and toNaked cannot set to true at the same time. | | toNaked | Boolean | No | Redirects requests to the WWW domain to the naked (root) domain. Defaults to false. Both toWww and toNaked cannot set to true at the same time. | | pathToLowerCase | Boolean | No | Redirects requests with capital letters in the path to the same path, but lowercase. Defaults to false. | | removeTrailingSlash | Boolean | No | Redirects requests with a trailing slash to the same path, without a slash. Defaults to false. | | persistQueryString | Boolean | No | When set, the query string from the original request will be persisted to the redirect location. Defaults to false (default behavior for Express). | | redirectCode | Integer | No | Sets the redirect code to be used by default. Valid values are 301 and 302. Defaults to 302. | | callNextOnRedirect | Boolean | No | When set to true, the next() function will be called in the middleware after the redirect has taken place. Defaults to false. | | deferRedirectToNext | Boolean | No | When set to true, res.redirect() is not called in the middleware. Instead, an instance of CleanRedirect is saved to res.locals and available for further governance in the middleware that follows. | | customRedirects | Function | No | This is a function that accepts three arguments (req, res, redirector) and is called before calling res.redirect(). Pass this in to include custom redirect logic using conditions and setters and getters for the CleanRedirect object (see below). |

Ideally, this middleware should come before any other redirect-related logic, globally, using the app.use() method. However, you can also pass different configurations into different areas of your application.

Methods for CleanRedirect

There are two cases in which there is direct access to the object (an instance of CleanRedirect) that stores all the original and target URL data:

• Within the function passed to the customRedirects option.
• In later middleware, through the res.locals.cleanRedirect property, when passing a value of true to deferRedirectToNext.

In these situations, there are getters and setters available to further modify the configuration of the redirect and values of the target URL which will be passed into the res.redirect() method.

Getter Methods

| Name | Type | Description | |-----------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | protocol | String | Get the target protocol. | hostname | String | Get the target hostname. | path | String | Get the target path. | queryString | String | Get the target queryString. | hash | String | Get the target hash. | requiresRedirect | Boolean | Compares the original URL data and the mutated values to decide if a redirect is needed or not. | redirectUrl | String | Returns the full string that will be passed into the res.redirect() method. | redirectCode | Integer | Get the configured redirect code (301 or 302).

Setter Methods

All setter methods return this and are thus chainable.

| Method | Description | |------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | setProtocol(string) | Set the target protocol. | setHostname(string) | Set the target hostname. | setPath(string) | Set the target path. | setQueryString(string) | Set the target queryString. | setHash(string) | Set the target hash. | setPersistQueryString(boolean) | Set the option to persist the query string on the target URL. | setRedirectCode(integer) | Set the redirect code to be passed into the res.redirect() method. | setPathOverride(string) | Set an explicit value for the path passed into the res.redirect() method. Can be utilized to use the path relative and back redirects supported by Express. When set, all target URL data will be ignored, and the value passed as an override will be directly passed into res.redirect().

:fire:   Acknowledgements

Alexey Chernyshov (@ft502 on Dribbble) - For such a beautiful logo!

:black_nib:   Author

Ray East (@raycharius) - Technical Product Manager by Day, NodeJS Developer by Night