roast logo

_redirects file

What is the _redirects file?

  • A plain text file in the root of your deploy with the file name _redirects for controlling routing logic
  • Each line is 3 fields separated by any amount of white space:
    /source/path /destination/path statusCode
  • The /sourcePath and /destinationPath must start with /
  • The status code field is optional and if not specified, defaults to 301.
  • Using 200 as a status code is a "rewrite" (or proxy), the user will not see the final/true destination.
  • a bang ! after the status code (no space) can be used for splat redirects to cause it to override all other routing
  • Comments start with #
  • White space around or between lines is ignored so use it for readability.

Why use the _redirects file?

For redirects, rewrites, and 404s. This includes avoiding CORS configuration by redirecting a same origin path to a remote API.
In other words, some additional control over the CDN's routing logic.

Routing order

This is the order that our routing logic uses to apply rules from the _redirects file and uploaded files.

  1. splat redirects in force mode (put a ! after the status code to put a splat redirect in force mode)
  2. server-side rendered page
  3. non-splat redirects
  4. uploaded file
  5. splat redirects

Example use cases

Rewrite 404s as /index.html

(for single-page apps using pushstate URLs like Angular, React, etc.)

/* /index.html 200

200 rewrite/proxy splat (wildcard)

(for avoiding CORS config on your server)

(wildcards (asterisks) can only be at the end of a sourcePath and if used, the destinationPath must have :splat at the end)

/api/v1/* http://example.com/api/v1/:splat 200

301 redirect /documentation to /docs

(for redirecting old paths to new paths to preserve SEO, also note: 301 is the default status code)

/documentation /docs

302 redirect /documentation to /docs

(same as above, but use 302 instead of the default of 301)

/documentation /docs 302

200 rewrite/proxy /documentation to /docs

/documentation /docs 200

404 rewrite

/documentation /myCustom404Page 404

200 rewrite wildcard to another domain force mode (rare use case)

/* https://google.com/:splat 200!
note the bang at the end of the status code (no space) - that's called "force mode" which causes this splat/wildcard to be processed before anything else

200 rewrite wildcard to another path force mode (rare use case)

/* /docs/:splat 200!
note the bang at the end of the status code (no space) - that's called "force mode" which causes this splat/wildcard to be processed before anything else

301 redirect wildcard to another domain force mode (rare use case)

/* https://google.com/:splat 301!
note the bang at the end of the status code (no space) - that's called "force mode" which causes this splat/wildcard to be processed before anything else

301 redirect wildcard to another path force mode (rare use case)

/* /docs/:splat 301!
note the bang at the end of the status code (no space) - that's called "force mode" which causes this splat/wildcard to be processed before anything else