Routing Pragmas Explained

The yourspace.yml file uses a pragma system inspired by compiler directives. Each route can carry inline hints that tell the edge how to handle traffic.

The basics

A route looks like this:

routes:
  /api/*:
    target: origin
    cache: none
  /assets/*:
    target: cache
    cache: 30d
    edge: nearest

Available pragmas

target

Where the request goes:

• origin — proxy to your backend
• cache — serve from edge cache, fall back to origin
• edge-nearest — serve from the geographically closest node

cache

How long to cache:

• none — always hit origin
• 7d, 30d, 1y — duration shorthand
• immutable — cache forever (use with hashed filenames)

edge

Which edge nodes serve this route:

• nearest — closest to the user (default)
• all — replicate to every node
• region:us,eu — limit to specific regions

Cascading

Rules cascade top-to-bottom. More specific paths override general ones:

routes:
  /*:          { target: edge-nearest }
  /api/*:      { target: origin, cache: none }
  /api/health: { target: origin, cache: 5s }

The /api/health endpoint gets a 5-second cache even though /api/* says none.

Pragmas keep config readable. No DSL, no build step, just YAML with intent.