Custom Routing is only available for Sites hosted through CloudCannon. If you host your Site externally, or use CloudCannon in Headless Mode, Custom Routing will not work.
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:
- 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.
- 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:
A regular expression or plain string defining the url to match. The urls will always start with a / character. Implicit ^ and $ on each value.
The new URL to replace the current path including regex parameters.
One of 200, 301, 302, 307, 308, 404, 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, 404, and 410 change the URL that is served resulting in a single request. When using these statuses, the "to" field must refer to a path on the same site, with the domain and protocol excluded.
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.
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.
{
"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.
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:
A regular expression or plain string defining the url to match. The urls will always start with a / character. Implicit ^ and $ on each value.
A list of header names and values to add to the matching request
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'
The value to return in the header
{
"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.