Managing URLs with redirects and rewrite paths

Learn how to configure redirects and rewrites in your FastStore project to manage user access to your content.

In this guide, you will learn how to configure redirects and rewrites in your FastStore project. These tools help you manage user access to your content by automatically directing users from one URL to another or mapping custom URLs to existing page templates.

Redirects automatically take users from one URL to another. They are useful when pages have been moved, renamed, or removed. For example, if a page has been moved or renamed, the redirect ensures the user is taken to the new location.

Rewrites allow you to map custom URLs to existing page templates without changing the URL in the browser. This is useful when you want to hide complex or dynamic URL structures from users while maintaining clean and SEO-friendly URLs. For example, you can map a custom URL, such as /sale, to an existing Product Listing Page (PLP) template.

In summary:

Redirects change both the URL the user sees and the destination.
Rewrites keep the URL the same but change the destination internally.

These two tools enhance content organization, help maintain a good user experience, and ensure search engines continue to index the correct content.

Redirect behavior and caveats

Before configuring redirects, it's important to understand how they behave in FastStore and what caveats apply.

Native routes take precedence

FastStore prioritizes native pages (e.g., product, collection, and brand pages) over redirect rules. If a redirect's source path matches a native page, the redirect will be ignored. For example, if /fall-sale is a live native collection page, a redirect rule from /fall-sale to /fall will not work. The collection page will render instead. To make the redirect work, you must unpublish or disable the native page (/fall-sale). To disable a collection page, follow these steps:

Access the Admin and go to Catalog > Collections.
Click on the collection name you want to disable.
Click COLLECTION SETTINGS.
In Schedule, change the End date to a date before the Start date.
Click Save.

For more information on how to manage a collection, see the Delete and edit a collection guide.

If the source path of this native page is published by the Headless CMS, you must also unpublish it. To unpublish in the Headless CMS, follow these steps:

Access the Admin and go to Storefront > Headless CMS.
Click on the page name you want to unpublish.
Click Unpublish and choose Unpublish now.

You can also schedule to unpublish the page by clicking Add to Release.
Click Unpublish.
Click Save.

For more information on how to manage a page in the Headless CMS, see the Managing pages in the Headless CMS guides.

Query strings are not forwarded by default

Query string parameters (e.g., ?key=value) are not forwarded in redirects by default. For example, a rule /from → /to will redirect /from?key=value to /to, dropping the ?key=value portion.

Creating redirects

FastStore allows you to configure redirects through the discovery.config.js file. This configuration is based on Next.js redirects.

Projects hosted on Vercel have redirect limits, such as a maximum of 1,024 redirects in the array and a maximum string length of 4,096 for source and destination properties. (For details, see Vercel's Redirects article.) If you need to configure more than 1,024 redirects, see the (Beta) Enabling redirects using the enableRedirects flag section for an alternative workflow.

Open your FastStore project in your preferred code editor and go to the discovery.config.js file within your project directory.
Inside discovery.config.js, add the redirects function. This function will define your redirect rules, for example:

_10account: "{accountName}", _10… _10async redirects() { _10 const redirects = require('./src/redirects.json'); _10 return redirects; _10},

The redirects function requires the redirects.json file, which you will create in the next step. This file contains the redirect definitions.

Go to the src folder, create the redirects.json file, and add the following:


_10[
_10    {
_10        "source": "/office",
_10        "destination": "/about",
_10        "permanent": true
_10    }
_10]

Property name	Description
`source`	Original URL pattern that triggers the redirect. In this example, any URL starting with `/office` will be redirected.
`destination`	New URL to which users are sent. Here, `/about` is the destination for users coming from `/office`.
`permanent`	The type of redirect. Set to `true` for a permanent (308 status code) redirect, which search engines will cache. Set to `false` for a temporary (307 status code) redirect.

For more information about each property, refer to the Next.js documentation.

Run yarn dev to start your project in development mode.
Open a browser and go to the old URL (e.g., /office). If the redirect is set up correctly, you should be automatically redirected to the new URL (e.g., /about).

(Beta) Enabling redirects using the `enableRedirects` flag

For projects requiring more than 1,024 redirects, you can enable the enableRedirects flag in the discovery.config.js file. This flag lets you manage redirects through the Redirects feature in the VTEX Admin.

This workflow, which uses both a code configuration and the Redirects interface, is currently in beta.

Update your FastStore project to version 3.2.0 or higher. To do this, open your project in a code editor.
Open a terminal and run the following command to update the FastStore packages to the latest version:

_10yarn upgrade -L --scope @faststore
With your FastStore project open, navigate to the discovery.config.js file in the project directory.
Within the experimental section, add enableRedirects: true to enable the redirects feature in the project, for example:

discovery.config.js
_10… _10experimental: { _10 ... _10 enableRedirects: true, _10}, _10…
Run yarn dev to check for and address any errors before deploying this change to production.
Create a new branch and open a pull request to deploy the changes made in the discovery.config.js file to production.

Once the change is live, you can manage the store's redirects in VTEX Admin by following the instructions in Managing URL redirects.

Creating rewrites

FastStore leverages Next.js rewrites to create custom routes while using existing Product Listing Page (PLP) templates. This allows you to map specific URLs to templates defined in Headless CMS, providing flexibility in content organization and URL structure.