Section J
Performance
Server rendering by default, streaming for below-the-fold data, CDN image transforms, and Hydrogen's sub-request cache for runtimes with a cache store (Oxygen, workers).
Storefront API caching & cache strategies
Cache.long()/short()/none() opt in per query. Caching only engages when the client is given a cache (Oxygen/worker). Node dev has none, so this app doesn't pass one.
- Hydrogen API
CachecreateRunWithCachecreateFetchWithCacheCachingStrategy- Data
- Requires a CacheStorage runtime
- Docs
.claude/skills/hydrogen-storefront-client/references/caching.md
Strategy objects (Cache-Control semantics)
{
"Cache.long()": {
"mode": "public",
"maxAge": 3600,
"staleWhileRevalidate": 82800
},
"Cache.short()": {
"mode": "public",
"maxAge": 1,
"staleWhileRevalidate": 9
},
"Cache.none()": {
"mode": "no-store"
}
}Uncached Storefront API round trip just now: 27 ms (mock API adds MOCK_API_QUERY_LATENCY_MS of simulated latency).
On Oxygen, pass cache + waitUntil to createStorefrontClient, then opt in per query. Hydrogen never caches mutations, GraphQL errors, or responses marked private, and cart/customer reads must never pass a strategy.
const client = createStorefrontClient({ type: "public", requestContext,
config: { storeDomain, publicStorefrontToken, cache: await caches.open("hydrogen"), waitUntil } });
await client.graphql(PRODUCTS, { variables, cache: Cache.long() }); // never for cart/customerServer rendering, streaming & loading states
Loaders return promises for slow, non-critical data; <Await> + <Suspense> stream them in. The PDP streams recommendations and reviews this way.
- Hydrogen API
React Router <Await>Suspense- Data
- Any
Shell rendered at 2026-11-19T04:18:04.853Z
Deferred loader data streamed in at 2026-11-19T04:18:06.051Z (≈1.2 s after the loader started).
export async function loader() {
return { critical: await getCritical(), slow: getSlowThing() /* not awaited */ };
}
<Suspense fallback={<Skeleton />}><Await resolve={slow}>{(v) => …}</Await></Suspense>Image optimization
Hydrogen ships no Image component. A tiny helper adds ?width=&height=&crop= to Shopify CDN URLs and builds srcset.
- Hydrogen API
shopifyImageUrl (app helper)- Data
- Shopify CDN
- Docs
.claude/skills/hydrogen-image/SKILL.md



[ "https://cdn.shopify.com/s/files/1/0926/5994/1398/files/16404741b926c45969c5395c196b3ce3.png?v=13028826&width=120&height=150&crop=center", "https://cdn.shopify.com/s/files/1/0926/5994/1398/files/16404741b926c45969c5395c196b3ce3.png?v=13028826&width=320&height=400&crop=center", "https://cdn.shopify.com/s/files/1/0926/5994/1398/files/16404741b926c45969c5395c196b3ce3.png?v=13028826&width=640&height=800&crop=center" ]