Skip to main content

Caching

tip

Hydrogen 2.0 is out now. These archival Hydrogen 1.0 docs are provided only to assist developers during their upgrade process. Please migrate as soon as possible.

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.

Note: If you’re interacting with personalized or private data, then you need to override these defaults to meet your needs.

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 strategyCache control headerCache duration
CacheShort()public, max-age=1, stale-while-revalidate=910 seconds
CacheLong()public, max-age=3600, stale-while-revalidate=828001 Day
CacheNone()no-storeNo cache
CacheCustom()Define your own cache control headerCustom

Learn how to build your own caching strategy.

Example

import {CacheShort} from '@shopify/hydrogen';
response.cache(CacheShort());

Cache options

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

export interface AllCacheOptions {
mode?: string;
maxAge?: number;
staleWhileRevalidate?: number;
sMaxAge?: number;
staleIfError?: number;
}
NameDescription
modeSets 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.
maxAgeCorrelates with the max-age cache control header. Instructs the cache how long to store an entry.
staleWhileRevalidateCorrelates 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.
sMaxAgeCorrelates with the s-maxage cache control header. Instructs the cache how long to store an entry on CDN or proxy caches.
staleIfErrorCorrelates 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.

Note: There are other available cache control headers, but some of them aren't applicable to Hydrogen. For example, the no-cache option instructs the browser to not use the cached entry until it returns a 304 (Not Modified) status from server. However, the Hydrogen server doesn't send a 304 status on a request.

Sub-request caching

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.

Learn how to modify sub-request caching.

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. By default, Hydrogen implements a CacheShort() strategy for all full-page requests.

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.

Learn how to modify full-page caching

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:

public, max-age=1, stale-while-revalidate=9

Caching in development

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:

┌── Cache control header for http://localhost:3000/collections/freestyle-collection
│ public, max-age=3600, stale-while-revalidate=82800

│ query shopInfo public, max-age=43200, stale-while-revalidate=43200
│ query CollectionDetails public, max-age=1, stale-while-revalidate=9
│ query indexContent public, max-age=60, stale-while-revalidate=600
│ query Localization public, max-age=3600, stale-while-revalidate=82800
└──

Note: During development, disable cache in your browser's developer tools to make sure the latest changes are visible in your browser. For example, you can disable cache in Chrome DevTools by visiting the Network tab.

Sub-request caching is disabled by default during development. Learn how to enable sub-request caching.

Caching in production

Learn common tasks for managing caching in production.

Next steps