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.
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 |
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:
|
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.
Related hooks
Anchor link to section titled "Related hooks"- Improve your app's loading performance with streaming SSR and Suspense.