EDU-18478 - Adicionar necessidade de ticket para ativar feature de redirects

[barbara-celi]

Summary

EDU-18478

---

Type of change

• New content — Adds new documentation.
• Content update — Improves existing documentation (clarity, structure, examples, accuracy).
• Bug fix — Fixes markdown issues.
• Editorial fix — Spelling, grammar, or minor copy edits that don’t change meaning.
• Content removal — Deletes deprecated or obsolete content.

---

Checklist

• The content follows the VTEX Style Guide.
• Markdown renders correctly (headings, lists, tables, callouts).
• Links, images, code blocks, and examples are valid.
• Terminology, product names, and API references are consistent.
• Frontmatter (title, description, tags, slug) is correct
• Files follow the expected folder structure and naming conventions.

---

AI review instructions

This repository supports automated AI reviews for Markdown files in the docs folder, except docs/localization.

To run reviews on this PR, add at least one of the following labels:

• AI style review: evaluates tone and adherence to VTEX style guidelines.
• AI grammar review: identifies grammar and spelling issues.

Once at least one label is added, the review(s) will run automatically.

After the review is completed, the corresponding label will be removed and the label AI reviewed will be added to the PR.

Note

To rerun a review, remove and add the desired label again.

[github-actions]

👁️‍🗨️ Preview changes on Developer Portal

You can use the link below to load the Developer Portal in preview mode with the changes from this branch:

👉 Open preview environment

Below is the list of modified pages and their corresponding preview URLs:

File	Preview URL	Sidebar
docs/faststore/docs/routing/managing-urls-with-redirects-and-rewrite-paths.mdx	https://developers.vtex.com/docs/guides/faststore/routing-managing-urls-with-redirects-and-rewrite-paths	⚠️ Missing from navigation.json

[github-actions]

✏️ Grammar review summary

docs/faststore/docs/routing/managing-urls-with-redirects-and-rewrite-paths.mdx

Fixed minor typographic issues, including missing spaces after blockquote characters and a double space after a comma.

---

Was this feedback useful?

• Yes
• No

Review made on commit cc2c0cc

[github-actions]

🔍 Documentation feedback for docs/faststore/docs/routing/managing-urls-with-redirects-and-rewrite-paths.mdx

Here is the review of your Guide based on the specified guidelines.

---

1. General Feedback

The guide is clear, informative, and provides accurate technical instructions. However, it deviates from the VTEX Developer Portal Guide rules in terms of frontmatter metadata, document structure, and step formatting.

Specifically:

• Missing Frontmatter: The mandatory slug and createdAt fields are missing.
• Missing Sections: The document lacks a formal ## Before you begin section and a main ## Instructions section.
• Step Headings: The tasks are not organized under sequential ### Step N - Imperative title headings.
• Imperative Verbs: Several numbered list items do not start with imperative verbs (e.g., starting with prepositions like "Inside", "With", or "Within").

---

2. Actionable Feedback

Frontmatter

• Add the mandatory slug field (e.g., managing-urls-with-redirects-and-rewrite-paths).
• Add the mandatory createdAt field with an ISO 8601 timestamp.

Structure

• Add a ## Before you begin section right after the introduction to list prerequisites (e.g., having a FastStore project).
• Group all actionable steps under a main ## Instructions section.
• Restructure the tasks into sequential subsections using the format ### Step N - Imperative title. For example:
  • ### Step 1 - Disable conflicting native pages
  • ### Step 2 - Create redirects using discovery.config.js
  • ### Step 3 - Enable redirects via VTEX Admin (Beta)
  • ### Step 4 - Configure rewrites
• Add a ## Next steps section at the end of the guide to suggest follow-up actions.

Tone and Voice (Rule R2.5)

• Ensure every numbered list item starts with an imperative verb.
  • Correction: Change "Inside discovery.config.js, add..." to "Add the redirects function inside discovery.config.js..."
  • Correction: Change "With your FastStore project open, navigate..." to "Navigate to the discovery.config.js file..."
  • Correction: Change "Within the experimental section, add..." to "Add enableRedirects: true within the experimental section..."
  • Correction: Change "In Schedule, change..." to "Change the End date in Schedule..."

---

3. Suggested Revision

---
title: "Managing URLs with redirects and rewrite paths"
slug: "managing-urls-with-redirects-and-rewrite-paths"
excerpt: "Learn how to configure redirects and rewrites in your FastStore project to manage user access to your content."
createdAt: "2026-06-02T14:38:58.465Z"
updatedAt: "2026-06-02T14:38:58.465Z"
---

In this guide, you'll 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 takes users 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.

## Before you begin

Before configuring redirects and rewrites, ensure you have:
- A FastStore project set up and running.
- Access to the VTEX Admin with the necessary permissions to manage Catalog, Collections, and Headless CMS.

## Instructions

To manage URLs with redirects and rewrites in your FastStore project, follow the steps below.

### Step 1 - Disable conflicting native pages

FastStore prioritizes native pages (such as product, collection, and brand pages) over redirect rules. If a redirect's source path matches a native page, the redirect will be ignored. To make the redirect work, you must unpublish or disable the native page.

To disable a collection page:

1. **Access** the Admin and go to **Catalog > Collections**. 
2. **Click** the collection name you want to disable. 
3. **Click** `COLLECTION SETTINGS`.
4. **Change** the **End date** in **Schedule** to a date before the **Start date**. 
5. **Click** `Save`.

    > ℹ️ For more information on how to manage a collection, see the [Delete and edit a collection](https://newhelp.vtex.com/docs/tutorials/creating-collections-beta#delete-and-edit-a-collection) guide.

To unpublish a page in the Headless CMS:

1. **Access** the Admin and go to **Storefront > Headless CMS**.
2. **Click** the page name you want to unpublish.
3. **Click** `Unpublish` and choose `Unpublish now`.
4. **Click** `Unpublish` again to confirm.
5. **Click** `Save`.

    > ℹ️ For more information on how to manage a page in the Headless CMS, see the [Managing pages in the Headless CMS](https://newhelp.vtex.com/en/docs/tutorials/managing-pages) guides.

### Step 2 - Create redirects using discovery.config.js

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](https://vercel.com/docs/edge-network/redirects#configuration) article.) If you need to configure more than 1,024 redirects, see the [(Beta) Enabling redirects using the `enableRedirects` flag](#step-3---enable-redirects-via-vtex-admin-beta) section for an alternative workflow.

1. **Open** your FastStore project in your preferred code editor and go to the `discovery.config.js` file within your project directory.
2. **Add** the `redirects` function inside `discovery.config.js` to define your redirect rules:

    ```javascript discovery.config.js mark=3:6
    account: "{accountName}",
    …
    async redirects() {
        const redirects = require('./src/redirects.json');
        return redirects;
    },
    ```

    >ℹ️ The `redirects` function requires the `redirects.json` file, which you'll create in the next step. This file contains the redirect definitions.

3. **Create** the `redirects.json` file inside the `src` folder and add your redirect definitions:

    ```json src/redirects.json
    [
        {
            "source": "/office",
            "destination": "/about",
            "permanent": true
        }
    ]
    ```

    | 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](https://nextjs.org/docs/pages/api-reference/next-config-js/redirects) documentation.

4. **Run** `yarn dev` to start your project in development mode.
5. **Open** a browser and go to the old URL (e.g., `/office`) to verify that you are automatically redirected to the new URL (e.g., `/about`).

### Step 3 - Enable redirects via VTEX Admin (Beta)

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

>⚠️ This workflow, which uses both a code configuration and the [Redirects](https://help.vtex.com/tutorial/managing-url-redirects) interface, is currently in beta.

1. **Update** your FastStore project to version `3.2.0` or higher by opening your project in a code editor.
2. **Open** a terminal and run the following command to update the FastStore packages:
    
    ```bash
    yarn upgrade -L --scope @faststore
    ```

3. **Navigate** to the `discovery.config.js` file in your project directory.
4. **Add** `enableRedirects: true` within the `experimental` section of `discovery.config.js`:

    ```javascript discovery.config.js mark=4
    …
    experimental: {
        ...
        enableRedirects: true,
    },
    …
    ```

5. **Run** `yarn dev` to check for and address any errors before deploying.
6. **Create** a new branch and open a pull request to deploy the changes to production.

>⚠️ After deploying this change, open a ticket with [VTEX Support](https://help.vtex.com/en/support) to request the CDN-side configuration required to forward query string parameters. Otherwise, if you configure a redirect using rules such as `/from` → `/to`, a request to `from?key=value` will be redirected to `/to` rather than `/to?key=value`, so the query string parameter is not preserved.

### Step 4 - Configure rewrites

FastStore leverages Next.js rewrites to create custom routes while using existing Product Listing Page (PLP) templates.

1. **Refer** to the [Using rewrites with PLP template](https://developers.vtex.com/docs/guides/faststore/headless-cms-multiple-page-template#product-listing-page-plp-template-selection-criteria) section in the Multiple Page Templates documentation to map specific URLs to templates defined in Headless CMS.

## Next steps

- Learn more about [Managing URL redirects](https://help.vtex.com/tutorial/managing-url-redirects--3UJuFrU8imSVWg134mkvJV) in the VTEX Admin.
- Explore [Multiple Page Templates](https://developers.vtex.com/docs/guides/faststore/headless-cms-multiple-page-template) to further customize your store's layout.

---

Was this feedback useful?

• Yes
• No

Review made on commit cc2c0cc