Edge Configuration

Reference

Globals

Key	Required	Fixed Values	Examples	Description
version	Yes	v1 v2	v2	Altitude Edge Configuration Version
provider	Yes	cloudflare	cloudflare	Cloud Provider
routes	Yes		See example below	Defines routes for a site
conditionalHeaders	No		See example below	Defines conditional headers

Version 2.0

Routes

It is optional to start the pathPrefix with ’/‘.

Function or Static Route

There are 4 required key/value pairs in every route, with additional fields dependent on what is mounted on the route.

Key	Required	Fixed Values	Examples	Description
pathPrefix	Yes		/ /blog robots.txt	The path this route is hosted on
name	Yes		ssr ssg favicon.ico	Name of this route (must only be lowercase alphanumeric and dashes)
type	Yes	- static - function - proxy	function static proxy	Determines if the route is for a function, static asset or proxy
directory	Yes		dist public	The location of the source code to be mounted on this route
filename	No		favicon.ico robots.txt	Optionally specify a single file to be mounted on this route
shield	No	Shield Location *	Manchester Tokyo	Describes the location to forward all requests to before reaching the origin of this route
streaming `Coming soon!`	No	- true - false		Optionally allow bytes to be relayed from the origin response without buffering of this route

Proxy Route

Key	Required	Type	Examples	Description
pathPrefix	Yes	String	/ /proxy-route	The path this proxy is hosted on
name	Yes	String	proxy	Name of this route (must only be lowercase alphanumeric and dashes)
type	Yes	String	proxy	The type of proxy route is always ‘proxy’
url	Yes	String	https://proxy.thgaltitude.com	The url the route will be proxied to

Adding a New Route

When adding a new route to your altitude yaml ensure it’s always added at the bottom of the routes list.

When adding a new function or proxy route to a previously deployed site there is the possibily of a small amount of downtime where the route serves a 503. To mitigate this, please split your deployment of new functions or proxies into two parts.

First, deploy your site with the new route in your altitude yaml to deploy the new function or link the new proxy.
Then, redeploy your site with the code that calls the route you defined.

Notes

* Shield Locations:

London
Manchester
Frankfurt
Madrid
New York City
Los Angeles
Toronto
Johannesburg
Seoul
Sydney
Tokyo
Hong Kong
Mumbai
Singapore

Example Route Config

...
routes:
  - pathPrefix: /
    name: <your function/site name>
    type: function
    directory: .
    build:
      command: build
      output:
        directory: <your projects build command>
        filename: <worker filename (for e.g. _worker.js)>
        staticDirectory: static/ssr
...

Conditional Headers

⚠️ Notice: This feature is in still development and not ready for general access. If you haven’t been referred to it, please ignore this section

The conditional headers feature allows dynamically adding new headers onto requests to your site, depending on the existence and value of an original request header. Example

There are 5 required key/value pairs for each conditional header.

Key	Required	Examples	Description
matchingHeader	Yes	X-Request-Header	The header who’s value will be checked for a match on the given pattern.
pattern	Yes	isApp ([^,]+),([^,]+)	A regex pattern used to check the value of a given header for a match.
newHeader	Yes	X-New-Header	The name of the new header created.
matchValue	Yes	true $1	The value of the new header created if a match was found. Capture groups are supported.
noMatchValue	Yes	false	The value of the new header created if no match was found.

Notes

When defining the pattern the regex used must cover the whole header value. Eg for atest needs a regex of .*t(.*) not t(.*).
If a reference in the matchValue is made to a capture group that is out of bounds, it will be replaced with an empty string. Eg if the regex pattern has 2 capture groups and the match value is test=$3, the new header value on a match woud be test=.

Example Conditional Header Config

...
ConditionalHeaders:
  - matchingHeader: X-Request-Header
    pattern: ([^,]+),([^,]+)
    newHeader: X-New-Header
    matchValue: match=$1
    noMatchValue: no-match
...

If a site had the following config:
When a request goes to the site with the header X-Request-Header: foo,bar. A new header would be added to the request X-New-Header: match=foo before going to the origin of the site.

Builds

For source code which requires a build step, the following values are added under the build dictionary and its nested output dictionary:

Key	Required	Examples	Description
command	Yes	build	The name of the script command to run to build the app
output	Yes		The output sub-fields relate to the output of the build step
directory	Yes	dist	The location of the compiled source code
filename	No	_worker.js	Specifying the app entrypoint file for the route
staticDirectory	Yes	ssr-assets	The location of the static assets created by the build (do not repeat the build output directory in this)
staticFilename	No	gbr.svg	Specifying a single static asset within the staticDirectory

Variables (Build Time)

Altitude automatically generates a .env file in the root of your project at build time. Any existing .env file in the repository will be replaced with the variables specified for your environment.

This functionality works seamlessly with Vite-based tooling but may require additional configuration for other frameworks.

Example .env file:

# API keys
API_KEY=your_api_key_here
SECRET_KEY=your_secret_key_here

# Environment settings
ENVIRONMENT_URL=https://thisisconfig.com