Set up server-side redirects
This tutorial explains how to set up server-side redirects using Builder's Data model.
Server-side redirects guide visitors from one URL to another before the page loads. Use redirects to phase out old URLs without breaking links or to transition to new naming conventions.
Overview
- Redirects run on the server, so the intermediate URL does not display.
- Each redirect maps a source URL to a destination URL and can optionally mark the redirect as permanent with a 301 HTTP status.
- Manage redirects in Builder using a single Data model without code changes until deployment.
Prerequisites
- An app in the framework of your choice with the appropriate Builder SDK installed.
- Integrate your app with a Data model. For details, see Integrate with structured Data.
Step 1: Create a Data model
Create a Data Model to define a structured container for your site's URL redirects.
To create a Data model:
- Go to Models.
- Click + Create Model.
- In the Name field, enter
URL Redirects. - In the Description field, enter
server-side redirects. - Click Create.
The video below demonstrates creating a new Data model called URL Redirects:
Step 2: Add custom fields to the model
Add custom fields to the model to store the redirect URLs and other settings for managing redirects in your content entries.
To add custom fields:
- On the Fields tab, click + New Field.
- In the Name field, enter
SourceUrland set the Type to Url. - Repeat the process to create
DestinationUrlwith type Url andRedirectToPermanentwith type Boolean. - Click Save.
The video below demonstrates adding custom fields such as SourceUrl, DestinationUrl, and RedirectToPermanent to the Data model.
Step 3: Create the content entry
To create URL Redirects entries:
- Go to Content and click + New Entry.
- Select URL Redirect as the model type.
- In the Name field, enter
/site/intro → /site/get-startedto make the entry easy to identify. - Assign values to each custom field:
SourceUrl,DestinationUrl, andRedirectToPermanent. - Click Save.
The following video demonstrates creating a content entry using the URL Redirects model and setting values for the custom fields.
Step 4: Update your codebase
Create or update the next.config.js file in the root directory:
This setup uses builder.getAll() to fetch all entries from the url-redirects model. Each entry is transformed into the format required by Next.js:
source: the original URL fromsourceUrldestination: the redirect target fromdestinationUrlpermanent:truefor permanent HTTP status code301,falsefor temporary HTTP status code302
For example, a redirect created in Builder from /old-page to /new-page with permanent set to true maps to:
The next.config.js file supports up to 1024 redirect entries. For more context, refer to Vercel's guide, How can I increase the limit of redirects or use dynamic redirects on Vercel? and for more comprehensive information, visit their Redirecting documentation.
Add a webhook
With Next.js sites, you need to trigger a rebuild for new redirects. Since Next.js evaluates the next.config.js only once when building an app, newly added redirects don’t take effect immediately. To cause this rebuild, use a webhook.
For this part of the tutorial, you need a webhook URL on the backend. If you're using Vercel, visit their Deploy hooks documentation.
To add a Webhook to the data model take the following steps:
- Go to Models.
- Open the URL Redirects model you made in Create a Data model.
- On the Advanced tab, go to Webhooks and click Edit.
- Click + Webhook.
- Expand the new Webhook 1 and paste your webhook URL into the URL field.
- Click Done.
The following video demonstrates how to set up a Webhook:
Create or update the next.config.js file in the root directory:
This setup fetches entries from the url-redirects model using fetchEntries(), passing the Builder public API key. Each entry is transformed into the format required by Next.js:
source: the original URL fromsourceUrldestination: the redirect target fromdestinationUrlpermanent: true for permanent HTTP status code 301, false for temporary HTTP status code 302
For example, a redirect created in Builder from /old-page to /new-page with permanent set to true maps to:
The next.config.js file has a 1024 entry count limit. For more context, refer to Vercel's guide, How can I increase the limit of redirects or use dynamic redirects on Vercel? and for more comprehensive information visit their Redirecting documentation.
Add a webhook
With Next.js sites, you need to trigger a rebuild for new redirects. Since Next.js evaluates the next.config.js only once when building an app, newly added redirects don’t take effect immediately. To cause this rebuild, use a webhook.
For this part of the tutorial, you need a webhook URL on the backend. If you're using Vercel, visit their Deploy hooks documentation.
To add a Webhook to the data model take the following steps:
- Go to Models.
- Open the URL Redirects model you made in Create a Data model.
- On the Advanced tab, go to Webhooks and click Edit.
- Click + Webhook.
- Expand the new Webhook 1 and paste your webhook URL into the URL field.
- Click Done.
The following video demonstrates how to set up a Webhook:
Create a new file named middleware.ts in the root directory:
This middleware fetches entries from the url-redirects model using builder.getAll(). Each redirect entry is checked against the requested path. When a match is found, the middleware issues a redirect:
- HTTP status code 308 for permanent redirects
- HTTP status code 307 for temporary redirects
For example, a redirect created in Builder from /old-page to /new-page with permanent set to true maps to:
This setup helps handle redirects at the edge, intercepting and rerouting requests dynamically based on Builder-managed rules.
Add a webhook
With Next.js sites, you need to trigger a rebuild for new redirects. Since Next.js evaluates the next.config.js only once when building an app, newly added redirects don’t take effect immediately. To cause this rebuild, use a webhook.
For this part of the tutorial, you need a webhook URL on the backend. If you're using Vercel, visit their Deploy hooks documentation.
To add a Webhook to the data model take the following steps:
- Go to Models.
- Open the URL Redirects model you made in Create a Data model.
- On the Advanced tab, go to Webhooks and click Edit.
- Click + Webhook.
- Expand the new Webhook 1 and paste your webhook URL into the URL field.
- Click Done.
The following video demonstrates how to set up a Webhook:
Create a new file named middleware.ts in the root directory:
This middleware fetches entries from the url-redirects model using fetchEntries(). Each redirect entry is checked against the requested path. When a match is found, the middleware issues a redirect:
- HTTP status code 308 for permanent redirects
- HTTP status code 307 for temporary redirects
For example, a redirect created in Builder from /old-page to /new-page with permanent set to true maps to:
Add a webhook
With Next.js sites, you need to trigger a rebuild for new redirects. Since Next.js evaluates the next.config.js only once when building an app, newly added redirects don’t take effect immediately. To cause this rebuild, use a webhook.
For this part of the tutorial, you need a webhook URL on the backend. If you're using Vercel, visit their Deploy hooks documentation.
To add a Webhook to the data model take the following steps:
- Go to Models.
- Open the URL Redirects model you made in Create a Data model.
- On the Advanced tab, go to Webhooks and click Edit.
- Click + Webhook.
- Expand the new Webhook 1 and paste your webhook URL into the URL field.
- Click Done.
The following video demonstrates how to set up a Webhook:
In this React with React Router set up, create a new file named redirects.tsx in the src/components directory, or as the setup indicates:
This code creates a React component that handles dynamic URL redirects:
- The
<RedirectHandler>component fetches and stores redirect rules from Builder usinguseEffect()anduseState(). Each rule includes a source URL, destination URL, and permanent status. - The component uses
useLocation()to monitor the current path and check for matching redirect rules. - For matches, the component uses
window.location.replace()for permanent (301) redirects or React Router’snavigate()for temporary (302) redirects. - If no redirect matches, the component renders its child components as usual.
In src/main.tsx, wrap the <Routes> component with RedirectHandler to monitor route changes. For more information, see the Routing of the React Router:
This setup helps evaluate route changes against the Builder-managed redirect list.
When fetching redirects from Builder, each entry is mapped into an object. For example, a redirect from /old-page to /new-page with permanent set to true becomes:
In this React with React Router set up, create a new file named redirects.tsx in the src/components directory:
This component fetches redirect entries using fetchEntries() to check the current URL with useLocation() and matches against the fetched rules.
Redirects are handled as permanent with window.location.replace() or temporary using navigate().
Wrap the routes with the <RedirectHandler> component inside the <BrowserRouter> to monitor all route changes for matching redirect entries:
This setup helps evaluate route changes against the Builder-managed redirect list.
A redirect entry in Builder with source /old-page, destination /new-page, and permanent set to true maps to:
Run the app locally and verify that visiting /site/intro redirects to /site/get-started.
Create a new file builderRedirects.ts in the /utilsdirectory:
The redirectsFromBuilder() function fetches redirect entries from Builder and maps them into a standard format. The findRedirectByRequestUrl() function checks if the request path matches any source URL.
In Remix, entry.server.tsx is the entry point for all server-side requests. Add the redirect logic at the top of the handleRequest function:
This setup fetches and checks redirect rules on every request. When a match is found, the app returns an HTTP 301 redirect for permanent redirects or 302 for temporary redirects. When no match is found, the request proceeds with standard server-side rendering.
Add a Webhook
When using static builds with Remix, you need to trigger a rebuild for new redirects. To cause this rebuild, use a webhook.
For this part of the tutorial, you need a webhook URL on the backend. If you're using Vercel, visit their Deploy hooks documentation.
To add a Webhook to the data model take the following steps:
- Go to Models.
- Open the URL Redirects model you made in Create a Data model.
- On the Advanced tab, go to Webhooks and click Edit.
- Click + Webhook.
- Expand the new Webhook 1 and paste your webhook URL into the URL field.
- Click Done.
The following video demonstrates how to set up a Webhook:
Create a new file named redirects.server.ts in the app/utils directory:
This function fetches redirect rules from Builder, checks if the current path matches a rule, and throws a Remix redirect response. Redirects use HTTP status code 301 for permanent redirects and 302 for temporary redirects.
In app/root.tsx, import and use the checkRedirect() function in the loader:
This loader checks each request for matching redirect rules and performs the redirect when needed.
Add a webhook
For static builds, a webhook is needed to trigger rebuilds when redirects change. For server-side rendering, redirects update automatically. Check your codebase to determine if you need a webhook or not. If you do need a webhook, follow the instructions below.
To add a Webhook to the data model take the following steps:
- Go to Models.
- Open the URL Redirects model you made in Create a Data model.
- On the Advanced tab, go to Webhooks and click Edit.
- Click + Webhook.
- Expand the new Webhook 1 and paste your webhook URL into the URL field.
- Click Done.
The following video demonstrates how to set up a Webhook:
Create a new file named builderRedirects.ts in the /utils directory:
The redirectsFromBuilder() function fetches redirect entries from Builder and maps them into a standard format. The findRedirectByRequestUrl() function checks if the request path matches any source URL.
In entry.server.tsx, import findRedirectByRequestUrl() and add the redirect logic at the top of the handleRequest() function:
This setup fetches and checks redirect rules on every request. When a match is found, the app returns an HTTP 301 redirect for permanent redirects or 302 for temporary redirects. When no match is found, the request proceeds with standard server-side rendering.
For example, a redirect created in Builder from /old to /new with permanent set to true becomes:
Add a Webhook
When using static builds with Remix, you need to trigger a rebuild for new redirects. To cause this rebuild, use a webhook.
For this part of the tutorial, you need a webhook URL on the backend. If you're using Vercel, visit their Deploy hooks documentation.
To add a Webhook to the data model take the following steps:
- Go to Models.
- Open the URL Redirects model you made in Create a Data model.
- On the Advanced tab, go to Webhooks and click Edit.
- Click + Webhook.
- Expand the new Webhook 1 and paste your webhook URL into the URL field.
- Click Done.
The following video demonstrates how to set up a Webhook:
Create a new file named redirects.server.ts in the app/utils directory.
This function fetches redirect rules from Builder, checks if the current path matches a rule, and throws a Remix redirect response. Redirects use HTTP status code 301 for permanent redirects and 302 for temporary redirects.
In app/root.tsx, import and use the checkRedirect() function in the loader.
This loader checks each request for matching redirect rules and performs the redirect when needed.
Add a webhook
For static builds, a webhook is needed to trigger rebuilds when redirects change. For server-side rendering, redirects update automatically. Check your codebase to determine if you need a webhook or not. If you do need a webhook, follow the instructions below.
The following video demonstrates how to set up a Webhook:
To add a Webhook to the data model take the following steps:
- Go to Models.
- Open the URL Redirects model you made in Create a Data model.
- On the Advanced tab, go to Webhooks and click Edit.
- Click + Webhook.
- Expand the new Webhook 1 and paste your webhook URL into the URL field.
- Click Done.
The following video demonstrates how to set up a Webhook:
Create a new file named BuilderRedirects.ts in the /src directory.
This function fetches redirect entries from the url-redirects model and maps them into a format usable by the Vue router.
In src/router/index.ts, import getRedirects() and add the redirect logic to a beforeEach() navigation guard:
This setup adds a global navigation guard that fetches redirect rules and checks each route change for a match. When a match is found:
- HTTP status code 301 redirects use
window.location.replace(). - HTTP status code 302 redirects use
next()for client-side routing.
For example, a redirect created in Builder from /site/old to /site/new with permanent set to true maps to:
Run the app locally and verify that visiting /site/intro redirects to /site/get-started.
Create a new file named useRedirects.ts in the composables directory:
This composable fetches redirect entries from the url-redirects model and maps them into a format usable by Nuxt middleware.
Create a new file named redirect.global.ts in the middleware directory:
This global middleware runs on every navigation page and checks for a matching redirect rule. When a match is found:
- HTTP status code 301 redirects use
navigateTo()withexternal: trueandredirectCode: 301 - HTTP status code 302 redirects use
navigateTo()withreplace: truefor client-side routing
For example, a redirect created in Builder from /site/old to /site/new with permanent set to true maps to:
Run the app locally and verify that visiting /site/intro redirects to /site/get-started.
In layout.tsx, add the following code above the onGet() request handler:
This code imports fetchEntries() from the Builder SDK, fetches redirect entries from the url-redirect model, and maps them into a usable format. The routesLoaded caches the results.
Update the onGet() request handler to include the following logic:
This code does the following:
- Loads redirect rules from Builder if uncached.
- Checks if the current path matches any source from the redirect rules.
- Redirects using HTTP status code 308 for permanent redirects (equivalent to 301) or 307 for temporary redirects (equivalent to 302).
For example, a redirect created in Builder from /site/old to /site/new with permanent set to true maps to:
Run the app and visit /site/intro to confirm that it redirects to /site/get-started.
Add a webhook
For Qwik sites using static-site generation, also known as SSG, you will need to trigger a rebuild for new redirects. To cause this rebuild, use a webhook.
For this part of the tutorial, you need a webhook URL on the backend. If you're using Vercel, visit their Deploy hooks documentation.
To add a Webhook to the data model take the following steps:
- Go to Models.
- Open the URL Redirects model you made in Create a Data model.
- On the Advanced tab, go to Webhooks and click Edit.
- Click + Webhook.
- Expand the new Webhook 1 and paste your webhook URL into the URL field.
- Click Done.
The following video demonstrates how to set up a Webhook:
Create or update the gatsby-node.js file in the root directory:
This setup fetches entries from the url-redirects model using builder.getAll() and registers redirects with Gatsby’s createRedirect() API. Each entry maps as follows:
fromPath: the original URL fromsourceUrltoPath: the redirect target fromdestinationUrlisPermanent:truefor HTTP status code 301,falsefor HTTP status code 302
For example, a redirect created in Builder from /old-page to /new-page with permanent set to true becomes:
Add a webhook
For static builds, a webhook is needed to trigger rebuilds when redirects change. For server-side rendering, redirects update automatically. Check your codebase to determine if you need a webhook or not. If you do need a webhook, follow the instructions below.
To add a Webhook to the data model take the following steps:
- Go to Models.
- Open the URL Redirects model you made in Create a Data model.
- On the Advanced tab, go to Webhooks and click Edit.
- Click + Webhook.
- Expand the new Webhook 1 and paste your webhook URL into the URL field.
- Click Done.
The following video demonstrates how to set up a Webhook:
Create or update the gatsby-node.js file in the root directory:
This setup fetches entries from the url-redirects model using fetchEntries() and registers redirects with Gatsby’s createRedirect() API. Each entry maps as follows:
fromPath: the original URL fromsourceUrltoPath: the redirect target fromdestinationUrlisPermanent:truefor HTTP status code 301,falsefor HTTP status code 302
For example, a redirect created in Builder from /old-page to /new-page with permanent set to true becomes:
Add a webhook
For static builds, a webhook is needed to trigger rebuilds when redirects change. For server-side rendering, redirects update automatically. Check your codebase to determine if you need a webhook or not. If you do need a webhook, follow the instructions below.
What’s next
- Learn how to integrate CMS data into your site.
- Review the concepts behind Data models to structure other dynamic data.
In entry.server.tsx, import findRedirectByRequestUrl() and add the redirect logic at the top of the handleRequest() function.