Redirects

Redirects live in a ROUTER file (no extension) at the root of the directory you publish. One rule per line: a status code, the pattern to match, and where to send it.

301   /contact   /about

ROUTER files are a Pro feature—publishing a project that contains one prompts you to upgrade right in the CLI if you haven't already. See Plans.

Status codes

Use 301 for content that has genuinely moved; 302 or 307 for temporary detours you expect to undo.

Pattern routes

Named segments capture parts of the path and substitute into the destination:

301   /my-blog/:title   /articles/:title

Now /my-blog/my-first-post redirects to /articles/my-first-post. Segment names are yours to choose. This is the tool for migrating URL schemes wholesale—for example, moving off a WordPress-style structure:

301   /:year/:month/:day/:slug   /blog/:slug

Query strings and trailing slashes

Rules match the path only. A request's query string rides along to the destination, so with 301 /contact /about, a request for /contact?ref=hn lands on /about?ref=hn. A trailing slash is forgiven too: /contact/ matches the /contact rule (an exact match elsewhere in the file still wins).

External redirects

The destination can be a full URL on another host:

307   /blog   https://medium.com/surge-sh

A complete ROUTER

301   /:year/:month/:day/:slug   /blog/:slug
301   /contact                   /about
307   /code                      https://github.com/sintaxi/surge

Rules are one per line and publish with the project like any other file—so your redirect table is versioned alongside your code, and rolling back a revision rolls back its redirects too. The ROUTER file itself is never served.

Note you don't need ROUTER rules for the redirects Surge already does automatically—trailing slashes, www folding, and HTTPS enforcement are covered in Clean URLs and SSL.

This page as markdown · every page in llms-full.txt