Caching

Hydrogen includes recommended caching strategies to help you determine which cache control header to set. The following table lists the available caching strategies and their associated cache control headers and cache durations:

Use the CacheNone() caching strategy to disable caching. You should consider disabling caching on authenticated pages to prevent leaking personal identifying information.

If you don't want to use the caching strategies provided by Hydrogen, then you can create your own to use in your project.

For example, you can create a cache control header with max-age=30, must-revalidate, no-transform:

Each mechanism accepts the same cache options API based on the Cache-Control HTTP Header:

While rendering a page in your Hydrogen storefront, it’s common to make one or more sub-requests to Shopify or other third-party data sources within server components. You should use sub-request caching to keep pages loading quickly for end-users. All sub-request have the default CacheShort strategy.

The following example shows how to implement useShopQuery for Shopify Storefront API queries:

The following example shows how to implement fetchSync for third-party requests:

When the cached entry becomes stale, if the age of the entry is still within the stale-while-revalidate window, then the stale version is returned and a new version is generated in the background.

In addition to sub-request caching, it’s helpful to cache the entire page response at the network edge and in the browser. This is the most useful for pages without dynamic or personalized data, like marketing pages or blog content. By default, Hydrogen implements a CacheShort() strategy for all full-page requests.

To modify full-page caching options, use the response property passed to the page server component:

Hydrogen provides sensible defaults for all sub-requests and full-page requests cache options.

By default, each full-page and sub-request receives the following cache options:

Sub-request caching is disabled by default during development.

To enable sub-request caching using an in-memory store, pass devCache: true to the second parameter of the Hydrogen Vite plugin:

To enable logging for the cache API status, set logger.showCacheApiStatus to true in your Hydrogen configuration file. The status of the cache updates on each query:

To enable logging for cache control headers, set logger.showCacheControlHeader to true in your Hydrogen configuration file. A cache control header report displays for each page request. The report includes the associated queries that built the request and the cache control headers:

To enable query cache busting on build, pass {purgeQueryCacheOnBuild: true} to the second parameter of the Hydrogen Vite plugin:

Sub-request caching uses an instance of Cache passed to the entry point.

For Worker-based runtimes, you can provide a cache option to handleRequest:

For Node.js-based runtimes, you can provide a cache option to hydrogenMiddleware:

Full-page caching is powered completely by cache-control headers on the Hydrogen response. By default, full-page caching is enabled as long as there is a cache available.

• useShopQuery
• fetchSync
• useQuery

• Improve your app's loading performance with streaming SSR and Suspense.