Configure route templates
Shopify storefronts have standard URLs, such as /products/{handle} and /collections/{handle}. Apps, Shopify browser modules, predictive search results, and old links all assume these URLs. If your storefront renders a resource at a different path, such as /p/{handle}, then Hydrogen needs to know so that it can build and redirect to your URLs instead.
Route templates are that shared configuration. You describe your app's URL shape once, in one manifest, and pass the same manifest to every Hydrogen primitive that builds or redirects storefront URLs. Route templates aren't page handlers. Your framework's router still renders every page.
Anchor to RequirementsRequirements
- Deploy a template, or add Hydrogen to an existing project.
- Know which paths your framework's router renders for each Shopify resource. Check your route config or route files, and any rewrites, catch-all routes, or localized route groups.
Anchor to Step 1: Create the manifestStep 1: Create the manifest
Create one manifest with createShopifyRouteTemplates(). Add a key only when your app renders a Shopify route at a path that's different from Shopify's standard path, or when you want Hydrogen to redirect a standard URL to one of your pages.
If your app uses Shopify's standard paths, then create an empty manifest. It still needs to exist, so there's one place to update if your routes change later:
Standard paths
lib/route-templates.tsIf your app uses custom paths, then add a template for each one:
Custom paths
lib/route-templates.tsThe React Router template renders products at /products/{handle} and doesn't render collection-scoped product URLs. It adds only productInCollection, so collection-scoped product URLs redirect to the product page:
React Router template manifest
app/lib/route-templates.tsVercel Shop, Vercel's Next.js template, uses Shopify's standard paths, so it calls createShopifyRouteTemplates() without any keys.
Anchor to Route template keysRoute template keys
Each key is a Shopify standard route, and each value is your app's path template for that route. Templates start with / and include the placeholders that the key requires.
| Key | Shopify standard path | Add this key when |
|---|---|---|
product | /products/:productHandle | Your app renders product pages at a different path. |
productInCollection | /collections/:collectionHandle/products/:productHandle | You want collection-scoped product URLs to redirect to a product page that your app renders. |
collection | /collections/:collectionHandle | Your app renders collection pages at a different path. |
collectionList | /collections and the legacy /products | Your app renders the collection list at a different path. |
page | /pages/:pageHandle | Your app renders Online Store pages at a different path. |
policy | /policies/:policyHandle | Your app renders store policies at a different path. |
blog | /blogs/:blogHandle | Your app renders blog pages at a different path. |
article | /blogs/:blogHandle/:articleHandle | Your app renders blog articles at a different path. |
cart | /cart | Your app renders the cart page at a different path. |
search | /search | Your app renders search results at a different path. |
The supported placeholders are :productHandle, :collectionHandle, :pageHandle, :policyHandle, :blogHandle, and :articleHandle. Hydrogen can't fill in any other placeholder.
Follow these rules when you write the manifest:
- Leave a key out when your app doesn't render that route. For example, if your storefront has no blog, then leave out
blogandarticle. - Don't add keys for standard paths, even to be explicit.
- Use strings, not functions. The manifest must be serializable.
- Don't include query strings or hashes. Hydrogen adds and keeps query parameters separately.
- Don't include market prefixes such as
/en-ca. Hydrogen adds the prefix from the request'si18n.pathPrefix. Refer to Markets.
Anchor to Step 2: Pass the manifest to every consumerStep 2: Pass the manifest to every consumer
Import the same routeTemplates object everywhere Hydrogen builds, redirects, or exposes storefront URLs. Don't create a separate manifest for each consumer. You pass it to the following APIs when you wire them:
| API | What it uses the manifest for | Guide |
|---|---|---|
handleShopifyRoutes() | Redirects Liquid-style ?variant={id} product URLs to your app's product path. | Request handlers |
handleShopifyRedirects() | Redirects Shopify's standard paths to your app's paths after your router returns a 404. Hydrogen doesn't check that the resource exists, so your page route handles missing resources. | Request handlers |
The routes prop of ShopifyScripts, or the routes option of initializeShopifyScripts() | Lets Shopify browser modules and agent tools build URLs that match your app. | Analytics and consent |
getPredictiveSearchItemUrl() | Links predictive search results to your app's paths. Query suggestions use the search template. | Add predictive search |
To check that Shopify's standard URLs reach your pages, wire the request handlers and then follow Verify your wiring.
