Redirects

What this page covers

You relaunched the store, the URL scheme moved from /old-page to /new-page, and you don't want every external link to drop visitors on a 404. You add a redirect in Cockpit, deploy, and the next hit on /old-page lands on /new-page with a 301.

This page explains what the storefront does once that redirect is in your laioutrrc.json. For the management UI (table, CSV import, bulk actions), see Cockpit: Redirects.

How a redirect reaches the site

Redirects you save in Cockpit are projected into rcProject.redirects at deploy time, the same way pages and markets are. The frontend reads that list and applies it in two places:

The server middleware handles direct hits: bookmarks, crawlers, hard reloads, links from email. The SPA middleware covers <NuxtLink> clicks and navigateTo() calls for paths Vue Router can't match to a built page.

The browser never receives the redirect list. Even projects with tens of thousands of rules don't ship them to the client bundle.

What gets matched

Exact paths

/old-page → /new-page matches /old-page and nothing else.

Pattern paths

Source paths can use :param segments, and the captured values are substituted into the target:

/p/:slug          →  /product/:slug
/c/:cat/p/:slug   →  /category/:cat/product/:slug

/p/sneaker resolves to /product/sneaker. Exact matches take priority over patterns automatically.

Trailing slashes

/old/ and /old resolve the same way, so a rule matches whichever shape the visitor typed. The root path / is the one exception and is always matched literally.

Note that redirect rules run after the trailing-slash normalizer. A request in the non-configured shape is 301-redirected to the configured one first, and your rules are then matched against the normalized path. See Trailing slashes for the policy and its exceptions.

Disabled redirects

Toggling Enabled off in Cockpit takes the rule out of the live matcher on the next deploy. The matcher only ever sees enabled rules.

Permanent vs temporary

Each row in Cockpit carries its own Permanent flag.

Both layers honor the same flag, so direct hits and in-app navigations produce the same status code.

Query strings and absolute targets

The original request's query string is appended to the target on both layers, so UTM tags and other marketing parameters survive the redirect:

/old-page?utm_source=newsletter  →  /new-page?utm_source=newsletter

Targets that start with http:// or https:// are treated as external URLs. The redirect leaves your domain entirely, which is what you want for sunset pages or handing traffic to a partner.

Caching at the edge

A redirect from your list depends only on the request URL, and it changes only with a deploy. On Laioutr Cloud and on Vercel, the storefront therefore sends it with Cache-Control: public, s-maxage=86400, and the CDN answers repeat requests for that URL without reaching your storefront.

The header carries no max-age, so browsers treat a 301 and a 302 exactly as before.

On other hosting, the storefront sends no cache header on a redirect. To add one, use the frontend-core:redirect:send hook, and only when your CDN clears its cache on every deploy.

Ordering with locale and built routes

Two interactions are worth knowing about:

Locale prefixes. Redirects fire before market detection. Write your targets in their canonical form without a locale prefix; market detection adds the prefix on the next hop.

Real pages. On the server, redirects win unconditionally. On the client, a path that resolves to a built page is never redirected. Avoid configuring redirect sources that shadow real pages, since direct hits and in-app clicks would then go to different places.

Related