Routing Pragmas Explained
The yourspace.yml file uses a small set of per-route keys — call them pragmas, inspired by compiler directives — that tell the edge how to handle traffic. Routes are declared as an ordered list; the first path that matches wins.
What's live today
Path matching, response headers, redirects, and per-route error
pages are active now. A route's target, cache,
ttl, and edge values parse and validate today but
currently resolve to static file serving regardless of value — the
origin-proxy, cache-layer, and edge-routing semantics described below land
with their respective workstreams. The fields are stable, so config you write
for them now keeps working once the behaviour ships.
The basics
A route looks like this:
routes:
- path: /api/*
target: origin
cache: none
- path: /assets/*
target: cache
cache: 30d
edge: nearest
Available pragmas
target
Where the request goes:
origin— proxy to your backendcache— serve from edge cache, fall back to originedge-nearest— serve from the geographically closest node
cache
How long to cache:
none— always hit origin7d,30d,1y— duration shorthandimmutable— cache forever (use with hashed filenames)
edge
Which edge nodes serve this route:
nearest— closest to the user (default)all— replicate to every noderegion:us,eu— limit to specific regions
Order matters
Rules are evaluated top-to-bottom and the first match wins, so the specific ones go first and catch-alls last:
routes:
- path: /api/health
target: origin
cache: 5s
- path: /api/*
target: origin
cache: none
- path: /*
target: edge-nearest
The /api/health endpoint keeps its 5-second cache because it's declared before the /api/* catch-all. Flip the order and /api/* would swallow it first.
Short keys, explicit ordering, one YAML file. No DSL, no build step, just config with intent.