@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.2

package/skills/hydrogen-storefront-client/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: hydrogen-storefront-client
+description: >
+  Guide for @shopify/hydrogen — the type-safe Storefront API
+  GraphQL client. Use when writing, modifying, or reviewing code that
+  creates a storefront client, writes GraphQL queries with gql(), handles SFAPI errors,
+  or wires up storefront data fetching in any framework.
+---
+
+# `@shopify/hydrogen`
+
+Type-safe GraphQL client for Shopify's Storefront API. Works anywhere you can call `fetch`.
+
+```ts
+import { createStorefrontClient, gql } from '@shopify/hydrogen'
+```
+
+## Environment Names
+
+Use these canonical environment variable names in app code and docs:
+
+- `PUBLIC_STORE_DOMAIN` for the Shopify store domain.
+- `PUBLIC_STOREFRONT_API_TOKEN` for the public Storefront API token.
+- `PRIVATE_STOREFRONT_API_TOKEN` for the private Storefront API token.
+- `PUBLIC_STOREFRONT_ID` for analytics `storefrontId`; use `"0"` when the app does not have a storefront ID.
+- `PUBLIC_CHECKOUT_DOMAIN` for app-level checkout-domain configuration such as CSP setup. Checkout links should come from cart data, usually `cart.checkoutUrl`.
+
+If the framework requires a prefix to expose client-side variables, preserve the canonical suffix and add only that framework prefix. For example: `NEXT_PUBLIC_STORE_DOMAIN`, `VITE_PUBLIC_STORE_DOMAIN`, or `PUBLIC_STORE_DOMAIN` depending on the framework. Never expose `PRIVATE_STOREFRONT_API_TOKEN` to the client.
+
+Environment variables are still a **server-side input boundary**. Do not read `process.env`, `import.meta.env`, or framework env modules from client components or modules imported by client components. Public-prefixed names mean a value is safe to serialize when needed; they are not permission to read env APIs in browser code. Browser UI should normally call same-origin Hydrogen endpoints/handlers. If a public value is genuinely needed in the browser, pass it from a server route/layout boundary as explicit data.
+
+---
+
+## Picking a client type
+
+`createStorefrontClient({type, requestContext, config})` takes a client type, a request context, and a client config object. Pick the type based on where the code runs, which token is safe there, and whether buyer context is available:
+
+| Type | Access | Best for |
+|------|--------|----------|
+| `"public"` | Public token, or tokenless | Default scaffold; browser-side fetches; tokenless mock.shop |
+| `"private"` | Private token with trusted `buyerIp` | SSR with buyer context |
+| `"private_no_buyer_context"` | Private token without buyer context | Prerendering, background jobs, webhooks |
+
+Default to a public client. `publicStorefrontToken` accepts `undefined`, which means tokenless access — there is no rate limit for tokenless clients, and it is all mock.shop supports. Always recommend a token-backed client (public or private) once the app targets a real store: token-based Storefront API access is required for product tags, metaobjects, metafields, menus, and customers. Public and private tokens can query the same token-required fields; the difference is whether the token is safe to expose and whether the request has trusted buyer context.
+
+### Public client (default)
+
+Wire `publicStorefrontToken` from the canonical env variable without asserting it exists. When `PUBLIC_STOREFRONT_API_TOKEN` is unset the client runs tokenless, so the same scaffold works against mock.shop before the user has tokens and upgrades in place when they add one. In env example files list the variable commented out (`# PUBLIC_STOREFRONT_API_TOKEN=`) rather than as an empty assignment: env loaders parse `PUBLIC_STOREFRONT_API_TOKEN=` as an empty string, and the client rejects empty tokens.
+
+This example belongs in a server-only module unless the config values are explicitly passed into browser code by a server boundary.
+
+```ts
+import { createStorefrontClient, createShopifyRequestContext } from "@shopify/hydrogen";
+
+const requestContext = createShopifyRequestContext({
+  request: { headers: new Headers() },
+  i18n: { country: "US", language: "EN" },
+});
+
+const client = createStorefrontClient({
+  type: "public",
+  requestContext,
+  config: {
+    storeDomain: process.env.PUBLIC_STORE_DOMAIN!,
+    publicStorefrontToken: process.env.PUBLIC_STOREFRONT_API_TOKEN,
+  },
+});
+```
+
+### Private client (SSR upgrade)
+
+Use when the app has a private token and trusted buyer context. Requires `buyerIp` to forward trusted buyer context. Resolve request-derived values before creating the client:
+
+```ts
+import { createStorefrontClient, createShopifyRequestContext } from "@shopify/hydrogen";
+
+function getBuyerIp(headers: Headers) {
+  const buyerIp = headers.get("oxygen-buyer-ip");
+  if (!buyerIp) throw new Error("oxygen-buyer-ip is required for private SFAPI clients");
+  return buyerIp;
+}
+
+const buyerIp = getBuyerIp(request.headers);
+const requestContext = createShopifyRequestContext({
+  request,
+  i18n: getLocaleFromRequest(request),
+  buyerIp,
+});
+
+const client = createStorefrontClient({
+  type: "private",
+  requestContext,
+  config: {
+    storeDomain: process.env.PUBLIC_STORE_DOMAIN!,
+    privateStorefrontToken: process.env.PRIVATE_STOREFRONT_API_TOKEN!,
+  },
+});
+```
+
+Hydrogen does not infer buyer IP headers. Apps decide how to build `buyerIp` based on their deployment and trusted request data. Common provider defaults:
+
+- Oxygen: `oxygen-buyer-ip`
+- Cloudflare: `CF-Connecting-IP`
+- Vercel: `x-forwarded-for`
+- Fly.io: `Fly-Client-IP` (parse `X-Forwarded-For` only when another reverse proxy sits in front)
+
+Use the same request-scoped Storefront client for Hydrogen route handlers, cart server handlers, and server data loaders when they share the same request data. Route, cart, and redirect handlers all accept any provided Storefront client.
+
+When using `handleShopifyRoutes`, pass the trusted `buyerIp` into `createShopifyRequestContext`. Both the SFAPI proxy and direct `client.graphql()` calls source buyer identity from that request context.
+
+### Private client without buyer context
+
+For queries not on behalf of a specific buyer (pre-rendering, static site generation). No buyer IP is forwarded.
+
+```ts
+const requestContext = createShopifyRequestContext({
+  request: { headers: new Headers() },
+  i18n: { country: "US", language: "EN" },
+});
+
+const client = createStorefrontClient({
+  type: "private_no_buyer_context",
+  requestContext,
+  config: {
+    storeDomain: process.env.PUBLIC_STORE_DOMAIN!,
+    privateStorefrontToken: process.env.PRIVATE_STOREFRONT_API_TOKEN!,
+  },
+});
+```
+
+---
+
+## Writing queries with `gql`
+
+`gql` is a pre-configured tag with baked-in SFAPI introspection. No codegen, no graphql-config — types are inferred at the type level from the query string.
+
+Customer Account API documents use `gql` from `@shopify/hydrogen/customer-account` instead. Keep the two helpers separate so Storefront API documents and Customer Account API documents cannot be mixed.
+
+```ts
+const SHOP_QUERY = gql(`query { shop { name description } }`);
+```
+
+Fragments compose via a second argument:
+
+```ts
+const PRODUCT_FIELDS = gql(`fragment ProductFields on Product { title handle }`);
+const QUERY = gql(`query { products(first: 10) { nodes { ...ProductFields } } }`, [PRODUCT_FIELDS]);
+```
+
+### Predictive search fragments
+
+When customizing predictive search, prefer Hydrogen's additive fragments instead of replacing the full query. This keeps base fields such as `trackingParameters`, handles, titles, images, and prices available to helpers and result links:
+
+```ts
+import { gql, makePredictiveSearchQueries } from "@shopify/hydrogen";
+
+const queries = makePredictiveSearchQueries({
+  fragments: {
+    product: gql(`
+      fragment PredictiveSearchProductFragment on Product {
+        vendor
+      }
+    `),
+  },
+});
+```
+
+Use the fragments with `createPredictiveSearchServerHandlers({ fragments })`, or use the generated query with `queryPredictiveSearch()`. Read the predictive search skill when wiring autocomplete UI or result URLs.
+
+### GraphQL type setup
+
+When adding Storefront API `gql()` documents to a TypeScript app, add Hydrogen's packed TypeScript plugin to the app's `tsconfig.json`:
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name": "@shopify/hydrogen/ts-plugin"
+      }
+    ]
+  }
+}
+```
+
+If the app already has TypeScript plugins, append this plugin without removing framework plugins such as Next.js `name: "next"`. If the app's `tsconfig.json` extends a generated framework config, add `compilerOptions.plugins` in the extending `tsconfig.json`.
+
+The plugin uses the Storefront and Customer Account API schemas shipped by `@shopify/hydrogen` and writes their generated environments at the project root.
+
+Keep `gql(\`...\`)` calls in server/route modules, not client/browser files or barrel files (e.g. an `index.ts` that re-exports everything). Bundlers can't tell whether a `gql()` call has side effects, so any `gql()` reachable from browser code gets bundled into the browser.
+
+If the app also authors Customer Account API documents, use `@shopify/hydrogen/customer-account`; the same plugin validates both APIs.
+
+This plugin provides inline GraphQL autocompletion, validation, and hover docs inside `gql()` calls. The editor must be configured to use the workspace TypeScript version (not the bundled one) — the bundled TS server does not load plugins.
+
+### Headless query validation
+
+Read `references/query-validation.md` when adding or changing `gql()` documents. The editor plugin does not run during `tsc`; add `hydrogen gql check` to a package script and run that script so invalid Storefront API fields fail in CI instead of surfacing as runtime GraphQL errors.
+
+### Typing query and fragment results
+
+`gql()` returns a **branded query string**, not a `gql.tada` document. Derive result and variable types from the `StorefrontApi` namespace exported by `@shopify/hydrogen`:
+
+```ts
+import { gql, type StorefrontApi } from "@shopify/hydrogen";
+
+const SHOP_QUERY = gql(`query { shop { name } }`);
+type ShopResult = StorefrontApi.ResultOf<typeof SHOP_QUERY>;
+type ShopVars = StorefrontApi.VariablesOf<typeof SHOP_QUERY>;
+```
+
+Because `gql()` is a branded string and not a `gql.tada` document, `gql.tada`'s `FragmentOf` does **not** apply (it will not compile). To get a standalone fragment's result type, compose it into a throwaway shape query and read `ResultOf` off that:
+
+```ts
+const PRODUCT_CARD = gql(`fragment ProductCard on Product { handle title }`);
+const PRODUCT_CARD_SHAPE = gql(
+  `query { products(first: 1) { nodes { ...ProductCard } } }`,
+  [PRODUCT_CARD],
+);
+export type ProductCardData =
+  StorefrontApi.ResultOf<typeof PRODUCT_CARD_SHAPE>["products"]["nodes"][number];
+```
+
+---
+
+## Fetching data
+
+### Variables and i18n auto-injection
+
+`$country` and `$language` variables are auto-injected from `requestContext.i18n` when declared in the query. Static clients still create a request context, usually with empty headers plus the resolved locale. You only pass the variables you own:
+
+```ts
+const PRODUCTS = gql(`
+  query Products($handle: String!, $country: CountryCode, $language: LanguageCode)
+  @inContext(country: $country, language: $language) {
+    collection(handle: $handle) { products(first: 10) { nodes { title } } }
+  }
+`);
+
+const { data } = await client.graphql(PRODUCTS, {
+  variables: { handle: "summer-sale" },
+});
+```
+
+User-provided values take precedence over auto-injected ones.
+
+### Request state storage
+
+`requestContext` is passed at client creation so request-scoped cookies, request-group IDs, response-header capture, personalized-response cache safety, and request aborts are centralized. Use one Shopify request context for Storefront and Customer Account clients in the same request. Per-call `signal` is optional when you need additional cancellation:
+
+```ts
+const { data } = await client.graphql(QUERY);
+const { data } = await client.graphql(QUERY, { signal });
+```
+
+`requestContext.signal`, per-call `signal`, and the client's timeout signal are raced automatically. At the final response boundary, append committed session headers first, then call `requestContext.applyResponseHeaders(response.headers)`.
+
+Read `references/caching.md` to cache catalog reads across sub-requests on Oxygen-style runtimes.
+
+---
+
+## Error handling
+
+**Transport errors throw. GraphQL errors are returned.**
+
+```ts
+import { StorefrontApiError, StorefrontTimeoutError } from "@shopify/hydrogen";
+
+try {
+  const { data, errors, headers } = await client.graphql(QUERY);
+  if (errors) { /* partial GraphQL errors — query succeeded but some fields failed */ }
+} catch (error) {
+  if (error instanceof StorefrontTimeoutError) { /* timed out */ }
+  if (error instanceof StorefrontApiError) { /* non-200, network failure, or JSON parse error */ }
+}
+```
+
+Every successful result includes `headers` (the raw `Headers` object from the response) — useful for forwarding `Set-Cookie` headers in SSR or reading rate-limit metadata.
+
+A 200 response with GraphQL `errors` does NOT throw — partial success is valid in GraphQL. Non-200 responses, timeouts, network failures, and JSON parse errors all throw `StorefrontApiError` (or the `StorefrontTimeoutError` subclass).
+
+`StorefrontApiError` carries GraphQL error context (`locations`, `path`, `extensions`) when available. `extensions.code` enables programmatic branching (e.g. retry on `"THROTTLED"`). `toJSON()` strips dev-only fields (`queryText`, `variables`, `stack`) — safe for error reporters.
+
+---
+
+## Testing
+
+Inject a mock `fetch` at construction — the client calls it instead of the global:
+
+```ts
+const mockFetch = vi.fn().mockResolvedValue(
+  new Response(JSON.stringify({ data: { shop: { name: "Test" } } })),
+);
+
+const client = createStorefrontClient({
+  type: "public",
+    requestContext: createShopifyRequestContext({
+      request: { headers: new Headers() },
+      i18n: { country: "US", language: "EN" },
+    }),
+  config: {
+    storeDomain: "test.myshopify.com",
+    publicStorefrontToken: "test-token",
+    fetch: mockFetch,
+  },
+});
+```
+
+---
+
+## Gotchas
+
+- **Private tokens throw in browser** — a `typeof document !== "undefined"` guard fires at construction.
+- **Env APIs are server-only** — examples that use `process.env` belong in server-only modules. Browser bundles may leave `process.env` undefined, inline stale build-time values, or accidentally expose config. Pass safe public values through server data when browser code needs them.
+- **Module-scope only for request-independent clients** — static public clients and `private_no_buyer_context` clients can be module-scoped when their `requestContext` uses static headers and static `i18n`. Private per-buyer clients and clients with a real incoming request context must be created per request.
+
+---
+
+## Framework recipes
+
+Before wiring a client into an app, check whether this skill has a reference file for the app's framework in `references/`. If one exists, read it and preserve that framework's request context, server data, and buyer-IP conventions. If there is no matching reference, use the core rules above: create request-scoped private clients only inside the server request lifecycle when buyer context exists, keep static public or no-buyer-context clients module-scoped only when they do not depend on request state, and forward captured response headers where the framework allows it.

package/skills/hydrogen-storefront-client/references/astro.md

@@ -0,0 +1,125 @@
+# Astro
+
+Astro pages run their frontmatter on the server, so `Astro.request` and `Astro.clientAddress` are available — but only on **server-rendered** pages. Prerendered pages have no request at all.
+
+## SSR
+
+Use `Astro.locals` to pass the storefront client from middleware to pages. The middleware creates the client once per request. The scaffold defaults to a public client; `PUBLIC_STOREFRONT_API_TOKEN` may be unset, which means tokenless access (all mock.shop supports). Once the app has a private token and trusted buyer context, switch to `type: "private"` and resolve `buyerIp` (e.g. from `Astro.clientAddress`) per the `hydrogen-storefront-client` buyer-IP guidance.
+
+```ts
+// src/middleware.ts
+import { defineMiddleware } from "astro:middleware";
+import {
+  createStorefrontClient,
+  createShopifyRequestContext,
+} from "@shopify/hydrogen";
+
+export const onRequest = defineMiddleware(async (context, next) => {
+  const requestContext = createShopifyRequestContext({
+    request: context.request,
+    i18n: { country: "US", language: "EN" },
+  });
+  const client = createStorefrontClient({
+    type: "public",
+    requestContext,
+    config: {
+      storeDomain: import.meta.env.PUBLIC_STORE_DOMAIN,
+      publicStorefrontToken: import.meta.env.PUBLIC_STOREFRONT_API_TOKEN,
+    },
+  });
+
+  context.locals.storefront = client;
+
+  const response = await next();
+  requestContext.applyResponseHeaders(response.headers);
+  return response;
+});
+```
+
+```ts
+// src/env.d.ts — type the locals object
+import type { StorefrontClient } from "@shopify/hydrogen";
+
+declare namespace App {
+  interface Locals {
+    storefront: StorefrontClient;
+  }
+}
+```
+
+```astro
+---
+// src/pages/products/[handle].astro — server-rendered page
+import { gql } from "@shopify/hydrogen";
+
+const PRODUCT_QUERY = gql(`
+  query Product($handle: String!) {
+    product(handle: $handle) { title description }
+  }
+`);
+
+const { handle } = Astro.params;
+const { data } = await Astro.locals.storefront.graphql(PRODUCT_QUERY, {
+  variables: { handle: handle! },
+});
+---
+<h1>{data?.product?.title}</h1>
+```
+
+This requires `output: "server"` in `astro.config.mjs` (all pages SSR by default). Individual pages that don't need request-time data can opt into static prerendering with `export const prerender = true`.
+
+## Static pages (no buyer IP)
+
+For prerendered pages — marketing, collection listings — use a module-scoped `private_no_buyer_context` client. No middleware needed since there's no request to read from.
+
+```ts
+// src/lib/storefront-static.ts
+import { createStorefrontClient, createShopifyRequestContext } from "@shopify/hydrogen";
+
+const requestContext = createShopifyRequestContext({
+  request: { headers: new Headers() },
+  i18n: { country: "US", language: "EN" },
+});
+
+export const staticStorefrontClient = createStorefrontClient({
+  type: "private_no_buyer_context",
+  requestContext,
+  config: {
+    storeDomain: import.meta.env.PUBLIC_STORE_DOMAIN,
+    privateStorefrontToken: import.meta.env.PRIVATE_STOREFRONT_API_TOKEN,
+  },
+});
+```
+
+```astro
+---
+// src/pages/collections/[handle].astro
+export const prerender = true;
+
+import { gql } from "@shopify/hydrogen";
+import { staticStorefrontClient } from "../../lib/storefront-static";
+
+const COLLECTION_QUERY = gql(`
+  query Collection($handle: String!) {
+    collection(handle: $handle) {
+      title
+      products(first: 20) { nodes { title handle } }
+    }
+  }
+`);
+
+const { handle } = Astro.params;
+const { data } = await staticStorefrontClient.graphql(COLLECTION_QUERY, {
+  variables: { handle: handle! },
+});
+---
+<ul>
+  {data?.collection?.products?.nodes?.map((p) => <li>{p.title}</li>)}
+</ul>
+```
+
+## Footguns
+
+- **`Astro.clientAddress` crashes prerendered pages** — it's only available during server rendering. Never access it (or `Astro.request`) in a page with `export const prerender = true`.
+- **Middleware runs on every request, including prerendered** — the `handle` hook fires even for prerendered routes. Guard buyer-context logic with a check if needed, or accept that the middleware sets up a client that simply won't be used on static pages.
+- **Astro v5 merged `hybrid` into `static`** — use `output: "server"` for SSR-by-default with static opt-in, or `output: "static"` (default) with `export const prerender = false` per-route for on-demand rendering.

package/skills/hydrogen-storefront-client/references/caching.md

@@ -0,0 +1,25 @@
+# Sub-Request Caching
+
+`Cache`, `createRunWithCache`, `createFetchWithCache`, and `CachingStrategy` are public exports of `@shopify/hydrogen` — the sub-request cache for catalog reads (products, collections, pages) on Oxygen-style runtimes that expose a `cache` store and `waitUntil`. Strategies are `Cache.long()`, `Cache.short()`, and `Cache.none()`. Pass `cache` (+ optional `waitUntil`) to `createStorefrontClient` and it builds `fetchWithCache` for you; reach for `createFetchWithCache` directly only when injecting a custom cached `fetch`.
+
+## Cache catalog reads through the client
+
+Pass `cache` (and optional `waitUntil`) to `createStorefrontClient` and opt in per query with `cache`. The client builds the cache key and skips caching GraphQL errors for you:
+
+```ts
+import { Cache, createStorefrontClient } from "@shopify/hydrogen";
+
+const client = createStorefrontClient({
+  type: "public",
+  requestContext,
+  config: { storeDomain, publicStorefrontToken, cache, waitUntil },
+});
+
+const { data, errors } = await client.graphql(PRODUCTS, { variables, cache: Cache.long() });
+```
+
+**Caching only engages when you pass `cache` per query.** Configuring `cache` on the client alone caches nothing — queries without a `cache` strategy (and all mutations) are never cached.
+
+## Never cache private data
+
+Do not pass a `cache` strategy to personalized reads (cart, customer); keep them on a request-scoped client. Cache mode `private` is unsupported — for buyer-specific caching use `createRunWithCache` with an explicit private key.

package/skills/hydrogen-storefront-client/references/nextjs.md

@@ -0,0 +1,121 @@
+# Next.js App Router
+
+## Dynamic pages
+
+Next.js server components don't receive a `Request` object. The pattern: a server-only cached factory that reads `headers()`, creates a request context from those headers, and creates a request-scoped client for that RSC request. The scaffold defaults to a public client; `NEXT_PUBLIC_STOREFRONT_API_TOKEN` may be unset, which means tokenless access (all mock.shop supports). Once the app has a private token and trusted buyer context, switch to `type: "private"` and resolve `buyerIp` per the `hydrogen-storefront-client` buyer-IP guidance (e.g. from trusted `x-forwarded-for` data).
+
+```ts
+// lib/storefront.ts
+import { headers } from "next/headers";
+import { cache } from "react";
+import {
+  createStorefrontClient,
+  createShopifyRequestContext,
+} from "@shopify/hydrogen";
+
+export const getStorefrontClient = cache(async () => {
+  const requestHeaders = await headers();
+  const requestContext = createShopifyRequestContext({
+    request: { headers: requestHeaders },
+    i18n: { country: "US", language: "EN" },
+  });
+
+  return createStorefrontClient({
+    type: "public",
+    requestContext,
+    config: {
+      storeDomain: process.env.NEXT_PUBLIC_STORE_DOMAIN!,
+      publicStorefrontToken: process.env.NEXT_PUBLIC_STOREFRONT_API_TOKEN,
+    },
+  });
+});
+```
+
+```ts
+// app/products/[handle]/page.tsx
+import { getStorefrontClient } from "@/lib/storefront";
+import { gql } from "@shopify/hydrogen";
+
+const PRODUCT_QUERY = gql(`
+  query Product($handle: String!) {
+    product(handle: $handle) { title description }
+  }
+`);
+
+export default async function ProductPage({ params }: { params: Promise<{ handle: string }> }) {
+  const { handle } = await params;
+  const storefront = await getStorefrontClient();
+  const { data } = await storefront.graphql(PRODUCT_QUERY, {
+    variables: { handle },
+  });
+  return <h1>{data?.product?.title}</h1>;
+}
+```
+
+The client is created inside the request path because `requestContext` is static on the client. Calling `headers()` makes this page dynamic. Route handlers and proxy files receive the actual `Request`; pass that request to `createShopifyRequestContext({ request, i18n })` there so the request URL and `request.signal` are preserved. When upgrading to a private client, also pass the trusted `buyerIp` (`createShopifyRequestContext({ request, i18n, buyerIp })`).
+
+## Static pages (no buyer IP)
+
+Pages that don't need buyer context — product listings, collection grids, marketing pages — can use `private_no_buyer_context` with a static request context. Because the component never calls `headers()`, `cookies()`, or reads `searchParams`, Next.js treats it as statically renderable and caches it at build time or via ISR.
+
+```ts
+// lib/storefront-static.ts - private client, no buyer context
+import { createStorefrontClient, createShopifyRequestContext } from "@shopify/hydrogen";
+
+const requestContext = createShopifyRequestContext({
+  request: { headers: new Headers() },
+  i18n: { country: "US", language: "EN" },
+});
+
+export const staticStorefrontClient = createStorefrontClient({
+  type: "private_no_buyer_context",
+  requestContext,
+  config: {
+    storeDomain: process.env.NEXT_PUBLIC_STORE_DOMAIN!,
+    privateStorefrontToken: process.env.PRIVATE_STOREFRONT_API_TOKEN!,
+  },
+});
+```
+
+```ts
+// app/collections/[handle]/page.tsx — statically rendered
+import { staticStorefrontClient } from "@/lib/storefront-static";
+import { gql } from "@shopify/hydrogen";
+
+const COLLECTION_QUERY = gql(`
+  query Collection($handle: String!) {
+    collection(handle: $handle) {
+      title
+      products(first: 20) { nodes { title handle } }
+    }
+  }
+`);
+
+export default async function CollectionPage({ params }: { params: Promise<{ handle: string }> }) {
+  const { handle } = await params;
+  const { data } = await staticStorefrontClient.graphql(COLLECTION_QUERY, {
+    variables: { handle },
+  });
+  return (
+    <ul>
+      {data?.collection?.products?.nodes?.map((p) => (
+        <li key={p.handle}>{p.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+This component never touches request-time APIs (`headers()`, `cookies()`, `searchParams`). With Cache Components, wrap catalog reads in explicit `"use cache"` functions and choose a `cacheLife` / `cacheTag`; do not use route-segment `revalidate`. All requests share one throttle bucket - fine for pages that serve the same data to every visitor. Use a per-request client from `getStorefrontClient()` (upgraded to `private`) when you need per-buyer isolation or personalized data.
+
+## `use cache` does not serialize `URLSearchParams`
+
+`use cache` serializes its arguments, so a `URLSearchParams` loses `.get` across the boundary. Pass a plain `string` and reconstruct `new URLSearchParams(string)` inside the cache-point:
+
+```ts
+// "use cache" cache-point
+async function fetchCollection(handle: string, searchString: string) {
+  const parsed = parseCollectionParams(new URLSearchParams(searchString));
+  // ...
+}
+```