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:

Sub-request caching
Full-page caching

Hydrogen also includes default values for each mechanism.

Caching strategies

Anchor link to section titled "Caching strategies"

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:

Caching strategy	Cache control header	Cache duration
`CacheSeconds()`	`public, max-age=1, stale-while-revalidate=9`	10 seconds
`CacheMinutes()`	`public, max-age=900, stale-while-revalidate=900`	30 minutes
`CacheHours()`	`public, max-age=1800, stale-while-revalidate=1800`	1 hour
`CacheDays()`	`public, max-age=3600, stale-while-revalidate=82800`	1 Day
`CacheWeeks()`	`public, max-age=604800, stale-while-revalidate=604800`	2 Weeks
`CacheMonths()`	`public, max-age=1296000, stale-while-revalidate=1296000`	1 Month
`CacheCustom()`	Define your own cache control header	Custom

Example

Anchor link to section titled "Example"

Build your own caching strategies

Anchor link to section titled "Build your own caching strategies"

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:

Cache options

Anchor link to section titled "Cache options"

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

Name	Description
`mode`	Sets options that don't need a duration: `no-store`: The response is prevented from being cached at any layer. This is useful for private or time-sensitive data. `private`: The response is cached in a user’s browser but not at the hosting or edge layer. This is useful for private or customized data. `must-revalidate`: The response must revalidate with the server when `max-age` time is expired.
`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.
`sMaxAge`	Correlates with the `s-maxage` cache control header. Instructs the cache how long to store an entry on CDN or proxy caches.
`staleIfError`	Correlates with the `stale-if-error` cache control header. Instructs how long browser is allow to use cached entry when entry returns a 5xx status error.

Sub-request caching

Anchor link to section titled "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. All sub-request have the default CacheSeconds 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.

Full-page caching

Anchor link to section titled "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. All sub-requests implement a default CacheSeconds() strategy.

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

Default values

Anchor link to section titled "Default values"

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:

Caching in development

Anchor link to section titled "Caching in development"

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, call setLoggerOptions and set showCacheApiStatus to true:

The status of the cache updates on each query:

To enable logging for cache control headers, call setLoggerOptions and set showCacheControlHeader to true:

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:

Busting query cache on build

Anchor link to section titled "Busting query cache on build"

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

Caching in production

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

Anchor link to section titled "Related hooks"

Next steps

Anchor link to section titled "Next steps"

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