diff --git a/docs/localization/managing-urls-with-redirects-and-rewrite-paths.md b/docs/localization/managing-urls-with-redirects-and-rewrite-paths.md new file mode 100644 index 0000000000..8c89b77ffd --- /dev/null +++ b/docs/localization/managing-urls-with-redirects-and-rewrite-paths.md @@ -0,0 +1,70 @@ +--- +title: "Managing URLs with redirects and rewrite paths" +slug: "managing-urls-with-redirects-and-rewrite-paths" +hidden: false +createdAt: "2024-09-18T10:00:15.623Z" +updatedAt: "" +--- + +In this guide, you will learn how to configure redirects and rewrites in your FastStore project to manage how users access your content. + +Redirects are used to take users from one URL to another automatically. This is useful when a page has 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 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. + +## Creating redirects + +FastStore allows you to configure redirects through the [`faststore.config.js`](https://developers.vtex.com/docs/guides/faststore/project-structure-config-options) file. This configuration is based on [Next.js redirects](https://nextjs.org/docs/pages/api-reference/next-config-js/redirects). + +> ⚠️ Projects hosted on Vercel have redirect limits such as, "Number of redirects in the array: 1,024 maximum" and "String length for `source` and `destination` parameters: 4.096 maximum." For more information, check the Vercel [Redirects](https://vercel.com/docs/edge-network/redirects#configuration) article. + +1. Open your FastStore project in your preferred code editor and go to the `faststore.config.js` file in your project directory. + +2. In `faststore.config.js`, add the `redirects` function. This function will define your redirect rules. For example: + + ```faststore.config.js mark=3:6 + account: "{accountName}", + … + async redirects() { + const redirects = require('./src/redirects.json'); + return redirects; + }, + ``` + + > ℹ️ The `redirects` function requires the `required.json` file, which you will create in the next step. This file contains the redirect definitions. + +3. Go to the `src` folder and create the `redirects.json` file. +In the `redirects.json` file, add the following: + + ```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 the users will be redirected to. In this case, `/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, check the Next.js documentation. + +4. Run `yarn dev` to start your project in development mode. + +5. Open a browser and go to the old URL (example: `/office`). If the redirect is set up correctly, you should be automatically redirected to the new URL (example: `/about`). + +## Creating rewrites + +FastStore leverages [Next.js rewrites](https://nextjs.org/docs/pages/api-reference/next-config-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. For more information on using rewrites with PLP templates, check 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 on the Multiple page templates documentation.