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.

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 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

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.