hydrogen-routing
Skill218 starsChanged 10 days agoMITView on GitHub
Guide for Hydrogen route templates and Shopify storefront URL routing. Use when adding, modifying, or reviewing createShopifyRouteTemplates, routeTemplates, custom Shopify resource or utility-page paths, handleShopifyRoutes, standard route redirects, ShopifyScripts routes, or predictive search result URLs.
1 other project uses a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- Shopify/hydrogenedited, first seen Oct 13, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 1
- Shopify/hydrogen★ 2.2k81% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository21 other files it gives its agents.
- AGENTS.mdAGENTS.md
- hydrogen-analyticsSkill
- hydrogen-cart-drawerSkill
- hydrogen-cart-metafieldsSkill
- hydrogen-cart-uiSkill
- hydrogen-collection-browserSkill
- hydrogen-customer-accountSkill
- hydrogen-imageSkill
- hydrogen-local-httpsSkill
- hydrogen-marketsSkill
- hydrogen-moneySkill
- hydrogen-oxygenSkill
- hydrogen-predictive-searchSkill
- hydrogen-request-handlersSkill
- hydrogen-setupSkill
- hydrogen-shop-paySkill
- hydrogen-smoke-testSkill
- hydrogen-storefront-clientSkill
- hydrogen-variant-formSkill
- remix-storeSkill
- testing-practicesSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 8 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
Create one route template manifest during app setup.
- Very specific: line 26
Create one routeTemplates object and pass the same object to every Hydrogen primitive that builds, redirects, or exposes Shopify storefront …
- Distinctive: line 41
If the app currently uses Shopify's default resource paths, create an empty manifest with an explanatory comment:
- Very specific: line 99
Only run handleShopifyRedirects() after framework routing has produced a 404.
- Distinctive: line 133
Do not include locale or market prefixes in route template values.
- Very specific: line 160
Create one routeTemplates manifest, even when it is empty.
- Distinctive: line 161
Add only keys whose Shopify route is rendered at a non-standard pathname.
- Distinctive: line 163
Keep route templates serializable.
- Distinctive: line 164
Do not query Shopify to verify resource existence before redirecting a standard route.
- Distinctive: line 165
Do not include query strings or hashes in route templates.
- Distinctive: line 166
Do not include i18n path prefixes in templates.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Hydrogen Routing
Hydrogen route templates describe the app's URL shape for Shopify standard storefront routes. They are shared configuration, not page handlers.
Create one route template manifest during app setup. It can be empty when the app uses Shopify's default storefront paths, but it should still be passed to Hydrogen primitives so there is one app-owned routing manifest to update if routes change later.
Routing is owned by the host framework and the app's router. Before deciding whether a template is needed, identify the framework, inspect how it declares routes, and verify which resolved path pattern actually renders each Shopify resource or utility page. Do not infer route support from filenames alone when the framework uses route config, middleware, rewrites, catch-all routes, or localized route groups.
Only add template keys for Shopify standard routes the app actually handles or intentionally canonicalizes. If the app does not render Shopify pages, does not have a blog, or does not support another route type, leave that key undefined so the route can remain a normal 404.
Core Primitive
Create one routeTemplates object and pass the same object to every Hydrogen primitive that builds, redirects, or exposes Shopify storefront URLs:
import { createShopifyRouteTemplates } from "@shopify/hydrogen";
export const routeTemplates = createShopifyRouteTemplates({
product: "/p/:productHandle",
collection: "/c/:collectionHandle",
article: "/journal/:blogHandle/:articleHandle",
cart: "/basket",
policy: "/legal/:policyHandle",
search: "/find",
});If the app currently uses Shopify's default resource paths, create an empty manifest with an explanatory comment:
// Shopify standard storefront routes are currently handled at their default paths.
// Add entries here if the app changes to custom Shopify resource or utility-page paths.
export const routeTemplates = createShopifyRouteTemplates({});Each key is a Shopify standard route identity. Each value is the app's custom pathname template for that identity. Templates must start with / and include the required named placeholders for that key. Add a key only when the app handles that route at a non-standard pathname, or when the app intentionally canonicalizes a standard Shopify variant such as productInCollection.
Shopify Standard Storefront Routes
Before adding a template key, inspect the app's router and compare its resolved paths to Shopify's standard storefront paths. For file-system routers, translate the framework's filename syntax into URL patterns. For config-based routers, read the route config. For middleware, rewrites, catch-all routes, and localized route groups, trace how the request path is normalized before it reaches the route.
product: Shopify standard path/products/:productHandle. Add this key only when the app renders product detail pages at a different path, such as/p/:productHandleor/shop/:productHandle. Leave it undefined when the app already handles/products/:productHandle.productInCollection: Shopify standard path/collections/:collectionHandle/products/:productHandle. Add this key when the app should canonicalize collection-scoped product URLs to a product page it handles, such as/products/:productHandle, or to a custom collection-scoped product path, such as/c/:collectionHandle/p/:productHandle. Leave it undefined if collection-scoped product URLs should 404.collection: Shopify standard path/collections/:collectionHandle. Add this key only when the app renders collection detail pages at a different path, such as/c/:collectionHandleor/shop/collections/:collectionHandle. Leave it undefined when the app does not render collections.collectionList: Shopify standard paths/collectionsand legacy/products. Add this key only when the app renders the collection listing at a different path, such as/catalog. Leave it undefined when the app handles/collectionsor does not render a collection listing.page: Shopify standard path/pages/:pageHandle. Add this key only when the app renders Shopify Online Store pages at a different path, such as/content/:pageHandleor/info/:pageHandle. Leave it undefined when the app does not render Shopify pages.policy: Shopify standard path/policies/:policyHandle. Add this key only when the app renders Shopify policies at a different path, such as/legal/:policyHandle. Leave it undefined when the app handles/policies/:policyHandleor does not render policy pages.blog: Shopify standard path/blogs/:blogHandle. Add this key only when the app renders blog landing/listing pages at a different path, such as/journal/:blogHandleor/articles/:blogHandle. Leave it undefined when the app does not render blogs.article: Shopify standard path/blogs/:blogHandle/:articleHandle. Add this key only when the app renders blog articles at a different path, such as/journal/:blogHandle/:articleHandleor/articles/:blogHandle/:articleHandle. Leave it undefined when the app does not render articles.cart: Shopify standard path/cart. Add this key only when the app renders the full cart page at a different path, such as/basket. Leave it undefined when the app handles/cartor has no full cart page.search: Shopify standard path/search. Add this key only when the app renders full search results at a different path, such as/find. Leave it undefined when the app handles/searchor has no full search page.
Supported placeholders are :productHandle, :collectionHandle, :pageHandle, :policyHandle, :blogHandle, and :articleHandle. Do not use extra dynamic placeholders such as :selectedOptions; Hydrogen cannot infer or pass values for placeholders outside the supported handle set.
Required Consumers
Pass the same routeTemplates object to all relevant Hydrogen primitives, even when it is empty.
Shopify Routes
Pass routeTemplates to handleShopifyRoutes() before framework routing so Liquid-style ?variant=<id> product URLs are recognized at the app's product path:
const shopifyRoute = handleShopifyRoutes({
request,
requestContext,
sessionManager,
storefrontClient,
routeTemplates,
handlers: [cartHandlers],
});Redirects
Pass routeTemplates to handleShopifyRedirects() so Shopify's default storefront paths redirect to the app's custom paths after the framework returns a 404:
const redirect = await handleShopifyRedirects({
request,
storefrontClient,
routeTemplates,
});Only run handleShopifyRedirects() after framework routing has produced a 404. Do not use route templates to preempt normal app routes.
ShopifyScripts
Pass route templates to ShopifyScripts so browser-side Shopify modules and agent tools can resolve Shopify storefront URLs through the app's URL shape after hydration:
<ShopifyScripts
shop={shop}
i18n={i18n}
routes={routeTemplates}
/>For non-component integrations, render getShopifyScriptTags() or renderShopifyScriptTags() during SSR, then pass the same routes: routeTemplates option to initializeShopifyScripts() during browser hydration.
Predictive Search
Pass route templates to getPredictiveSearchItemUrl() so predictive result links match the app's custom resource paths while preserving Shopify tracking parameters:
const href = getPredictiveSearchItemUrl(item, {
term,
routes: routeTemplates,
pathPrefix: i18n.pathPrefix,
});Predictive search falls back to Shopify's default routes when a template key is omitted from the manifest.
For query suggestions, pass the same route templates so a custom search route is used. Pass searchPath only when that link intentionally differs from the shared search route; an explicit searchPath takes precedence.
Markets And Path Prefixes
Do not include locale or market prefixes in route template values. Keep templates resource-relative:
createShopifyRouteTemplates({
product: "/p/:productHandle",
});not:
createShopifyRouteTemplates({
product: "/en-us/p/:productHandle",
});Hydrogen applies i18n.pathPrefix separately:
handleShopifyRoutes()reads it fromrequestContext.i18n.pathPrefixfor product?variant=redirects.handleShopifyRedirects()reads it fromstorefrontClient.requestContext.i18n.pathPrefix.ShopifyScriptsreceives it through thei18nprop or option.getPredictiveSearchItemUrl()receives it throughpathPrefix.
Rules
- Identify the framework and router before deciding which Shopify standard routes are handled.
- Inspect the app's actual route files before adding a template key.
- Create one
routeTemplatesmanifest, even when it is empty. - Add only keys whose Shopify route is rendered at a non-standard pathname.
- Reuse one
routeTemplatesobject across Shopify routes, redirects, ShopifyScripts, and predictive search. - Keep route templates serializable. Use strings, not callback functions.
- Do not query Shopify to verify resource existence before redirecting a standard route. Redirect to the app route and let that route handle missing resources.
- Do not include query strings or hashes in route templates. Consumers preserve or append query parameters separately.
- Do not include i18n path prefixes in templates.
Anti-patterns
- Passing route templates to
handleShopifyRedirects()but notShopifyScripts. - Passing route templates to
handleShopifyRedirects()but nothandleShopifyRoutes(). - Hard-coding predictive search links separately from
routeTemplates. - Creating different template objects for different Hydrogen routing consumers.
- Using callback URL builders for standard Shopify resources when a route template can describe the URL shape.
- Adding templates for default paths just to be explicit; keep the manifest empty or omit those keys instead.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

