Static site routing rules

​

What this covers

​

Where rules come from

​

_redirects

# Redirect a single page
/home            /                       301
# Splat: everything under /blog moves
/blog/*          /news/:splat
# Placeholders
/news/:year/:slug  /articles/:year/:slug
# Query string match
/store id=:id    /products/:id           301
# Rewrite (the URL does not change)
/app/*           /app/index.html         200
# Serve a page with a 404 status
/ecommerce/*     /store-closed.html      404
# Force a rule even when a file exists at the path
/index.html      /                       301!

• The default status is 301. Supported statuses: 200 (rewrite), 301, 302, 303, 307, 308, and 404, 410, 451 (answer with the page named by the destination).
• :name matches one path segment and * matches the rest of the path (last segment only). Both can be used in the destination. * is available as :splat.
• Matching ignores case and a trailing slash.
• The visitor’s query string is passed on to a redirect destination that has no query of its own.
• A 200 rewrite must point at a path on this site. Rewriting to another site (a proxy) is not supported; use a path forwarder on the domain instead.
• Conditions such as Country=, Language=, Role= and Cookie= need an edge runtime and are not supported. A line that uses one is skipped and reported.

​

_headers

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
/assets/*
  Cache-Control: public, max-age=31536000, immutable
  ! Server

​

app.yaml

services:
  site:
    build: { type: static, command: npm run build, publish: dist }
    domains: [www.example.com]
    routes:
      - { from: /blog/*, to: "/news/:splat", status: 301 }
      - { from: /store, to: "/products/:id", query: { id: ":id" } }
      - { from: /index.html, to: /, status: 301, force: true }
    headers:
      - path: "/*"
        values: { X-Frame-Options: DENY }
        remove: [Server]
    static:
      spa: true
      cleanUrls: true
      trailingSlash: remove
      notFound: 404.html

​

Order of evaluation

1. Rules, in order: app.yaml routes, then _redirects. The first rule that matches wins. A rule that is not forced (! or force: true) is skipped when a file exists at the requested path, so a stray rule cannot hide real content.
2. Files: the exact file, then path.html when clean URLs are on, then path/index.html. Trailing slash and clean URL redirects happen here.
3. Single page app fallback, when static.spa is on: a path with no file and no extension serves index.html with status 200. A missing /app.js still returns 404.
4. 404 page, served with status 404. If there is none, a plain 404 response.

​

Safety

• Redirect destinations are either a path on this site or an absolute http or https URL. A destination that starts with //, contains backslashes or whitespace, carries credentials, or uses a placeholder in its host is rejected, so a rule cannot become an open redirect.
• Values captured from the request are re-escaped before they are placed in a Location header.
• Header names and values are checked for control characters, so a rule cannot inject a second header.
• Matching uses linear time regular expressions, so a crafted URL cannot stall the ingress.

​

Limits

​

Problems and the deploy log

​

See the rules and test a URL

levelrail-cli static-sites routes show my-site
levelrail-cli static-sites routes test my-site /old --request-query "ref=x"
levelrail-cli static-sites routes lint my-site --redirects ./public/_redirects --headers ./public/_headers

​

Rollback