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. The root path / is the one exception and is always matched literally.

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.

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