Choose your preferred SSG:
Choose your preferred SSG:

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.

Routes

Routes are useful in two cases:

  1. 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.
  2. Push state routing: Certain SSGs output a single html file that is expected to load on multiple routes. JavaScript on that page will load different content based on the url.

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 200, 301, 302, 307, 308 or 410. Used to define the HTTP status code to use on the route.

301, 302, 307 and 308 codes trigger a redirect to a new location resulting in two requests. 200 and 410 change the URL that is served resulting in a single request.

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.

200 and 410 status codes are always forced.

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"
    },
    {
      "from": "/app/(.*)",
      "status": 200,
      "to": "/app/"
    }
  ]
}

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’

  • ‘referrer-policy’

  • ‘permissions-policy’

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.

Generated redirects

Create dynamic redirects from pages and data of your site.

During your build process, generate a file on _cloudcannon/routing.json and this will be used instead of .cloudcannon/routing.json from your source.

Was this article helpful? or Suggest an improvement >

Other Resources

  1. RE2