The catalog has moved to new URLs, but visitors still open old links from search results, bookmarks, and external publications. Without a route to a suitable new page, they get an error or land on the homepage and have to search for the product again. To fix the transition, first map old pages to new ones, then configure and test the redirects.
We’ll use a fictional educational store built with Next.js 15 and the App Router. Its red mug used to be at /products/red-cup; it is now at /catalog/red-mug. These are fictional URLs for illustration, not a published migration case study. For another catalog, you’ll need to create your own map and check that the new pages really replace the old ones.
Create a map of old URLs before writing code
Start with the URLs in the old sitemap, a product export, and known landing pages from analytics. Add URLs that are still linked from menus, articles, and partners. For each row, specify the new destination and why it matches. Where possible, match records by a stable product ID rather than just a similar name.
Our example has several different outcomes:
| Old URL | Decision | Reason |
|---|---|---|
/products/red-cup | /catalog/red-mug | Same product page, slug changed |
/products/blue-cup | /catalog/blue-cup | Same product page, category changed |
/products/discontinued-kit | Review deletion | No direct replacement yet |
The last row should not automatically redirect to the homepage. If the product is gone and there is no equivalent replacement, decide how to handle the missing page. If the page is still useful as information about a discontinued product, you can keep its content. The decision depends on the product; a redirect does not create a useful replacement by itself.
Check old category pages separately. The “Mugs” category and a single red mug product page serve different purposes, so redirecting one to the other needs justification. Before automating, make sure the chosen destination matches the old content and what visitors expect.
Set up a permanent server-side redirect
A permanent server-side redirect is appropriate for a final move. Google describes 301 and 308 as signals of a permanent move. This does not guarantee that every ranking will be preserved: search engines still need to process the new pages and other site signals.
In Next.js 15, you can define rules in next.config.ts. This educational example uses exact matches, with no general rule for unknown products:
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
async redirects() {
return [
{
source: '/products/red-cup',
destination: '/catalog/red-mug',
permanent: true,
},
{
source: '/products/blue-cup',
destination: '/catalog/blue-cup',
permanent: true,
},
]
},
}
export default nextConfigIf the file already exists, add the function to the existing configuration and preserve the other settings. Then rebuild the app and run the production version. A rule in a local file does not mean that a server running the previous release has started applying it.
According to the Next.js redirects documentation 15 permanent: true uses status 308, while false uses 307. These statuses preserve the request method. Test a normal page load using GET; an accidental POST to this URL does not become a GET just because it was redirected.
Next rules are checked before filesystem routes are resolved, but your own proxy or CDN may sit in front of the app. If the public response differs from the local one, find out which layer handled the old URL first.
Decide which parameters to preserve
An old URL may look like /products/red-cup?utm_source=partner. Parameters matter for analytics and sometimes identify the product itself, for example, /product?id=42. These are different cases, and a single folder-replacement rule cannot reliably handle both.
With a standard redirect, Next.js forwards the original query parameters, as described in the documentation. Our example does not remove marketing tags or convert id into a slug. Check the full Location, including the query string, before considering the behavior correct.
If the identifier is stored in the query, you need a separate ID map and an exact rule for handling it. Do not use next, returnUrl, or an arbitrary visitor-supplied parameter as the destination URL. Migration destinations must come from a verified configuration; otherwise, instead of a migration, you could create an open redirect to other sites.
For our store, the expected redirect with a tracking tag preserves the selected product. However, the new product page’s canonical can point to the clean primary URL. Setting a canonical and redirecting are different actions; the former does not move the visitor. A common domain-related mistake is covered in the article about metadataBase and canonical.
Record the parameter requirements in the migration map: which parameters are preserved, which determine the content, and which must not affect destination selection. Don’t label all parameterized URLs as duplicates without checking what those parameters mean.
Use a template only when the mapping is stable
If only the prefix changes and all slugs remain the same, you can consider a rule with a path parameter. But in our example, red-cup changed to red-mug, so a mechanical substitution would send it to the wrong URL. These exceptions need an exact map.
First, test a dozen different URLs: a short slug, an old category, a URL with nested segments, a URL with encoded characters, and a known exception. If the new destination cannot be determined unambiguously, keep explicit mappings. For a large catalog, you can generate the map from a data export, but verify each destination before building the configuration.
Order exceptions so that a broader rule does not catch them first. Also check existing redirects for domain normalization, HTTPS, and trailing slashes: together, they can create an unnecessary chain or a loop. Evaluate the entire public request path, not just one Next.js function.
Don’t let a template treat an arbitrary value as an existing product page. An unknown old URL with no map entry should follow a pre-agreed error behavior. This is a separate negative test for acceptance.
Check the entire redirect, not just the first status
In a production build, send a GET request to the old URL without automatically following redirects to see the first response. Then repeat the request while following redirects and save all headers. For example, in an approved test environment:
curl -sS -D old-headers.txt -o old-body.html \
'https://staging.example.ru/products/red-cup?utm_source=test'
curl -sS -L --max-redirs 5 -D chain-headers.txt -o final-page.html \
'https://staging.example.ru/products/red-cup?utm_source=test'In the first file, check 308 and the exact Location. In the second, check that there are no loops, confirm the final URL, and verify that the product page loads. The five-redirect limit is a safeguard for the test, not a recommendation to build a chain that long. Where possible, the old URL should go directly to the final relevant page.
A resulting 200 does not prove the redirect worked: open the final page and compare the product, title, and canonical. A homepage with 200 instead of the product page does not pass the check. Save the results for a URL with a tracking tag, a regular URL, an exception, and an unknown product.
After the public release, repeat the same requests through the live domain. Account for browser and CDN caching: permanent redirects may be cached. Then check the new pages using a technical audit, noting separately which URLs were included in the check.
Update links and define acceptance criteria
Redirects help with old inbound links, but internal links should already point to the new URLs. Update the catalog, menus, product recommendations, and articles. Keep the agreed primary pages in the sitemap; check that new pages’ canonicals point to the agreed URLs, not to the old category or domain.
The developer task should include the approved map, parameter rules, a list of exceptions, and test requests. Acceptance criteria: known old URLs lead to the corresponding final product pages, methods and parameters are handled as agreed, there are no loops, unknown URLs are not sent to arbitrary products, and the public release uses the same configuration that was tested.
Keep the map and test results with the migration task. After crawling, check errors and page selection in webmaster tools. If traffic changes, compare periods, inventory, and new pages before attributing everything to a single redirect.
The examples are based on Next.js 15. If you use a separate server, CDN rules, or a different router, first find out where redirects are executed: duplicate rules across multiple layers are especially difficult to check after subsequent updates.