Caching

Caching is a fundamental building block of a good shopping experience. Combined with streaming server-side rendering, caching ensures that buyers get the quickest response possible while also displaying the latest data.

Hydrogen provides two mechanisms for cache within applications:

Hydrogen also includes default values for each mechanism.

Cache options

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

Name Description
maxAge Correlates with the max-age cache control header. Instructs the cache how long to store an entry.
staleWhileRevalidate Correlates with the stale-while-revalidate cache control header. Instructs the cache how long after an entry’s max-Age is acceptable to serve a stale entry. Another request for fresh data is made in the background.
private Defaults to false. Correlates with the private cache control header. If private is set to true, then the entry is cached in a user’s browser but not at the hosting or edge layer. This is useful for private or customized data.
noStore Defaults to false. Correlates with the no-store cache control header. If noStore is set to true, then the entry is prevented from being cached at any layer. This is useful for private or time-sensitive data.

Sub-request caching

While rendering a page in your Hydrogen app, 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. The following example shows how to implement useShopQuery for Shopify Storefront API queries:

The following example shows how to implement useQuery 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.

Full-page caching

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.

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

Default values

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

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

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

Caching in development

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:

You can also preview the full-page caching headers in the network tab of your browser’s developer tools. The response header used is cache-control-preview.

A screenshot of the response headers

Caching in production

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

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

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. This means the network edge as well as the user’s browser is responsible managing full-page cache.

Next steps

On this page