Skip to content

Free shipping over $220

NOVA
NOVA

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.

Real HydrogenNeeds a store
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.

TypeScript
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/customer

Server 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.

Real Hydrogen
Hydrogen API
React Router <Await>Suspense
Data
Any

Shell rendered at 2026-11-19T04:18:10.865Z

Deferred loader data streamed in at 2026-11-19T04:18:12.062Z (≈1.2 s after the loader started).

TypeScript
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.

Real HydrogenCustom feature
Hydrogen API
shopifyImageUrl (app helper)
Data
Shopify CDN
Docs
.claude/skills/hydrogen-image/SKILL.md
Halo headphones at 120px
120px · cross-origin size n/a
Halo headphones at 320px
320px · cross-origin size n/a
Halo headphones at 640px
640px · cross-origin size n/a
[
  "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"
]
Next · KSEO

Your bag

Popular

Browse

Loading…
Demo mode