Skip to main content

Redirects

The handleShopifyRedirects function sends customers to the right page when your framework's router returns a 404 response. Use the function to apply the store's URL redirects and to redirect Shopify's default resource paths to your app's paths.

Import handleShopifyRedirects from @shopify/hydrogen.

Pass the same route templates to this function and to handleShopifyRoutes in the routeTemplates option.

Anchor to 404 redirects404 redirects

Anchor to handleShopifyRedirects
handleShopifyRedirects(
options
)

Finds the Shopify redirect for a request that your framework's router can't match. Call the function when the router returns a 404 response, and return that 404 response when the function resolves to null.

The function checks these redirects in order and returns the first match as a 301 response: /admin to the store's admin, Shopify's default resource paths to your route templates, same-origin return_to and redirect query parameters, and the store's URL redirects. The response already carries the request context's headers. When a redirect lookup fails, the function logs the error and resolves to null.

Anchor to handleShopifyRedirects-parametersParameters

Anchor to options
options
required

The unmatched request, the Storefront API client, and your app's route templates.

Anchor to handleShopifyRedirects-returnsReturns

Promise<Response | null>

A promise for the matched redirect response, or null when no redirect matches.

Examples

TypeScript

import { handleShopifyRedirects, type ShopifyRouteTemplates, type StorefrontClient } from "@shopify/hydrogen";

export async function withShopifyRedirects(
request: Request,
storefrontClient: StorefrontClient,
response: Response,
routeTemplates: ShopifyRouteTemplates,
) {
if (response.status !== 404) return response;

const redirect = await handleShopifyRedirects({
request,
storefrontClient,
routeTemplates,
});

return redirect ?? response;
}
Was this page helpful?