@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.2

package/skills/hydrogen-routing/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: hydrogen-routing
+description: >
+  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.
+---
+
+# 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:
+
+```ts
+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:
+
+```ts
+// 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/:productHandle` or `/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/:collectionHandle` or `/shop/collections/:collectionHandle`. Leave it undefined when the app does not render collections.
+- `collectionList`: Shopify standard paths `/collections` and 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 `/collections` or 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/:pageHandle` or `/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/:policyHandle` or 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/:blogHandle` or `/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/:articleHandle` or `/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 `/cart` or 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 `/search` or 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:
+
+```ts
+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:
+
+```ts
+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:
+
+```tsx
+<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:
+
+```ts
+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:
+
+```ts
+createShopifyRouteTemplates({
+  product: "/p/:productHandle",
+});
+```
+
+not:
+
+```ts
+createShopifyRouteTemplates({
+  product: "/en-us/p/:productHandle",
+});
+```
+
+Hydrogen applies `i18n.pathPrefix` separately:
+
+- `handleShopifyRoutes()` reads it from `requestContext.i18n.pathPrefix` for product `?variant=` redirects.
+- `handleShopifyRedirects()` reads it from `storefrontClient.requestContext.i18n.pathPrefix`.
+- `ShopifyScripts` receives it through the `i18n` prop or option.
+- `getPredictiveSearchItemUrl()` receives it through `pathPrefix`.
+
+## 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 `routeTemplates` manifest, even when it is empty.
+- Add only keys whose Shopify route is rendered at a non-standard pathname.
+- Reuse one `routeTemplates` object 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 not `ShopifyScripts`.
+- Passing route templates to `handleShopifyRedirects()` but not `handleShopifyRoutes()`.
+- 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.

package/skills/hydrogen-setup/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: hydrogen-setup
+description: >
+  End-to-end Hydrogen storefront setup orchestrator. Use whenever scaffolding a Hydrogen storefront from scratch into an existing application.
+---
+
+# Setting Up Hydrogen
+
+Set up Hydrogen in an existing or new repository by working through the step files in `steps/` in order.
+
+Assume the deterministic Hydrogen setup command has already installed `@shopify/hydrogen` and copied the packaged skills into the app. Do not redo package installation or skill copying from this LLM skill.
+
+## How To Work Through The Steps
+
+Read each step file and complete it fully before opening the next. Every step ends each of its phases with a "Continue when" checklist of observable criteria — do not move to the next phase or step until every criterion passes. Reusable domain knowledge lives in the standalone `hydrogen-*` skills the steps invoke; setup-specific details live in `references/`.
+
+## Verification Discipline
+
+- A "Continue when" checkbox passes only when you observed it pass: run the command, curl the route, or exercise the UI in this session. Reading code you just wrote is not verification.
+- After every step that changed code, run the app's `typecheck` script and fix failures before opening the next step. Type errors compound; catching them per-step is cheap, untangling ten steps of drift at the end is not.
+- Setup is **not complete** until the final verify step's commands have been executed in this session and passed. If you are about to summarize results and have not just run them, stop and run them. Reporting success with failing or unrun checks is a failed setup, not a finished one.
+
+1. `steps/1-inspect-app.md` — verify basic compatibility, identify the styling approach, detect the framework and its reference files.
+2. `steps/2-scaffold.md` — route conventions, environment variable names, server-side env access, Storefront API client with `hydrogen gql check`, API route handlers, Customer Account API.
+3. `steps/3-build-home-page.md` — server-rendered home page listing collections and products.
+4. `steps/4-collection-and-search.md` — collection and search browsing with URL-synced filters.
+5. `steps/5-cart.md` — the `/cart` route with progressive enhancement.
+6. `steps/6-product-detail-page.md` — product detail route with variant form and add to cart.
+7. `steps/7-shopify-runtime-scripts.md` — Shopify runtime scripts and framework navigation hook.
+8. `steps/8-cart-drawer-and-navbar.md` — cart drawer in the root layout, then the navbar with its cart trigger.
+9. `steps/9-account-page.md` — account page with customer profile and logout, plus the navbar account link.
+10. `steps/10-analytics.md` — consent-gated storefront analytics.
+11. `steps/11-verify.md` — the app's own checks, then runtime smoke tests.
+
+## App-Owned Concerns (Out Of Hydrogen Scope)
+
+`@shopify/hydrogen` ships typed Customer Account API queries and low-level Customer Account OAuth/session helpers, but apps still own framework cookie/session adapters, account UI, image optimization, and SEO. Do not invent package exports beyond the documented APIs. Build app-owned concerns with the framework's own primitives and Shopify API data:
+
+- **Account UI / session storage** — the `hydrogen-customer-account` skill wires sessions and OAuth handlers during scaffold, and the account-page step builds the minimal profile + logout UI, but the app owns the framework session adapter, richer account pages, and order history UI. Keep account tokens server-side or in encrypted HttpOnly cookies, and do not retry account mutations after a timeout unless the operation is externally idempotent.
+- **Image optimization** — use the framework's image component (or `<img srcset>`) with Shopify CDN URL transforms; do not expect a Hydrogen `Image` component.
+- **SEO** — render meta/Open Graph tags and JSON-LD `Product`/`BreadcrumbList` structured data with the framework's head/metadata API using Storefront API data.
+
+Mention these to the user when they are relevant to the storefront being built rather than skipping them silently.
+
+## Stop Conditions
+
+- No `package.json` in the current directory.
+- No server-capable framework detected.
+- The detected framework is configured for static output only and no server adapter or equivalent request lifecycle is present.
+- The user declines to overwrite a conflicting copied skill and the existing skill is too old or incompatible to continue safely.