Import CacheLong, CacheShort, CacheNone, and CacheCustom from @shopify/hydrogen; pass the desired strategy as the cache option on storefront.query calls inside Remix loaders
Use CacheLong() for static or rarely-changing data like product descriptions, CacheShort() for prices or inventory that change more frequently, and CacheNone() for personalized or cart-related data
CacheCustom({ maxAge, staleWhileRevalidate }) gives fine-grained control; set maxAge for the TTL and staleWhileRevalidate to allow Oxygen to serve stale content while fetching fresh data in the background
For content that changes on demand (e.g., a product just updated via Admin), use Oxygen's cache purge API or a Shopify webhook → purge integration rather than relying solely on TTL expiry
In the loader add the Cache-Control header to the response using CacheLong() with the built-in headers helper if you also want the browser or CDN to cache the rendered page, not just the API response
Test caching behavior by adding a Cache-Status header inspection in the Oxygen dashboard's request logs; look for HIT vs MISS vs EXPIRED statuses
Known gotchas
CacheLong and CacheShort control Oxygen's internal Storefront API response cache, not the HTML page cache — you need to set Cache-Control on the Response object separately if you want the rendered route cached at the edge
Personalised responses (with buyer identity or cart context) must use CacheNone; caching a personalized response at the edge can serve one customer's cart data to another
Oxygen's cache is scoped to the deployment environment — a new deployment automatically busts all cached responses, which can cause a cold-cache traffic spike; warm critical routes after deploy
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp