Configuring Custom Routing

Configure your CloudCannon’s hosting by configuring a single JSON file. Create a routing.json file in the .cloudcannon folder at the root of your file structure. When URLs are loaded through the file server, this file is loaded to extend the default behaviour. Add custom headers and configure redirects all in one place.

Producing invalid JSON in this file will break the build and prevent hosting being impacted. Error messages will be available in the build output.

Redirects

When you change your website’s structure, you should redirect the old URLs to the new pages. This ensures external links pointing to the old content and search engines can be redirected. Configure your routing.json to include an array under the routes key with the following keys:

from - Regex (Implemented using re2)

A regular expression or plain string defining the url to match. The urls will always start with a / character. Implicit ^ and $ on each value.

to - String

The new URL to replace the current path including regex parameters.

status - Number

One of 301, 302, 307 or 308. Used to define the HTTP status code to use on the route.

forced - Boolean

If forced is true (default), the redirect will take priority. If forced is false, the redirect will only run if no file exists on that route. This is useful if you have a greedy regex that you don’t want interfering with existing routes.

substitutions - Boolean

If substitutions is true (default),  the to option can use regex parameters. If substitutions is false, the to option will be used as is. This is useful if you have a URL with characters that resemble the regex parameters.

.cloudcannon/routing.json
{
  "routes": [
    {
      "from": "/documentation/(.*)",
      "to": "/docs/$1",
      "status": 308
    },
    {
      "from": "/cloudcannon/(.*)",
      "status": 302,
      "to": "https://cloudcannon.com/$1"
    }
  ]
}

Redirects will only occur if the from url doesn’t resolve to a file. Rules are read in order and the earliest matching rule is used.

Note

You can redirect to, but not from a URL fragment (e.g. #example-heading). The fragment is not passed to the server so, it cannot be processed by the redirect.

Custom Headers

Configure extra headers on any route. Meet security needs or change some behaviour. Configure your routing.json to include an array under the headers key with the following keys:

match - Regex (Implemented using re2)

A regular expression or plain string defining the url to match. The urls will always start with a / character. Implicit ^ and $ on each value.

headers - Array

A list of header names and values to add to the matching request

headers.name - String

The name of the header to configure. Allowed values are

  • ‘strict-transport-security’

  • ‘x-robots-tag’

  • ‘x-content-type-options’

  • ‘x-frame-options’

  • ‘x-xss-protection’

  • ‘access-control-allow-origin’

  • ‘access-control-allow-headers’

  • ‘access-control-allow-methods’

  • ‘content-security-policy’

  • ‘content-security-policy-report-only’

  • ‘expect-ct’

  • ‘sourcemap’

  • ‘large-allocation’

  • ‘content-type’

headers.value - String

The value to return in the header

.cloudcannon/routing.json
{
  "headers": [
    {
      "match": "/about/",
      "headers": [
        {
          "name": "Access-Control-Allow-Origin",
          "value": "example.com"
        }
      ]
    }
  ]
}

Headers are processed at the beginning of all calls. Rules are read in order and combined on all matching rules similar to how CSS works.

Was this article helpful? or Suggest an improvement >

Other Resources

  1. RE2