Skip to content

Force HTTPS, www <==> naked domain, remove trailing slash, to lower case, and custom redirects wrapped into one single, clean redirect.

License

Notifications You must be signed in to change notification settings

raycharius/clean-redirect

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

83 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Logo

All your redirect logic wrapped into one single redirect

Force HTTPS, remove trailing slash, to lower case, naked to www, and your own custom logic, as one redirect.

Get Started · Request Feature · Report Bug


npm NPM codecov Maintainability

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.

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

💾   Installation

Using NPM:

npm install --save clean-redirect

Using Yarn:

yarn add clean-redirect

🔍   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

👾   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().

🔥   Acknowledgements

@ft502 Alexey Chernyshov (@ft502 on Dribbble) - For the Clean Redirect logo!

✒️   Author

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