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 automatically caches responses from queries when using the Storefront client. You can disable or customize the cache for every single request to the Storefront API. This guide shows the different options available for caching.
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 |
---|---|---|
CacheShort() |
public, max-age=1, stale-while-revalidate=9 |
10 seconds |
CacheLong() |
public, max-age=3600, stale-while-revalidate=82800 |
1 Day |
CacheNone() |
no-store |
No cache |
CacheCustom() |
Define your own cache control header | Custom |
By default, each sub-request applies the CacheShort()
strategy with the following cache options:
The following is an example of how to pass a cache strategy to the Storefront client to cache product titles:
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 it's 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 the browser may use the cached entry when the entry returns a 5xx status error. |
Create a custom caching strategy
Anchor link to section titled "Create a custom caching strategy"If you don't want to use the caching strategies that Hydrogen provides, 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 data from third-party APIs
Anchor link to section titled "Cache data from third-party APIs"Requests to the Storefront API support cache options. However, if you're using raw fetch
for requests to third-party APIs, then the following behavior occurs:
- Every GET request is cached according to response headers.
- Manual POST requests are never cached automatically.
You can cache single sub-requests or wrap multiple sub-requests in a single closure before caching to allow atomic invalidation.
withCache
utility
Anchor link to section titled "withCache utility"Hydrogen provides a withCache
utility that allows caching third-party API calls and supports stale-while-revalidate options. This utility wraps an arbitrary number of sub-requests under a single cache key.
Step 1: Create and inject the utility function
Anchor link to section titled "Step 1: Create and inject the utility function"Similar to the Storefront client, the withCache
utility must be created in the entry file and passed in the Remix context. The following example shows how to use it with the Oxygen adapter for Remix:
Step 2 (optional): Add types for the utility function
Anchor link to section titled "Step 2 (optional): Add types for the utility function"For TypeScript projects, you can also add types for withCache
in the Remix context:
Step 3: Call withCache
from Remix loaders and actions
Anchor link to section titled "Step 3: Call withCache from Remix loaders and actions"After you inject the utility function in the Remix context, withCache
is available in Remix loaders and actions:
Step 4 (optional): Creating custom abstractions
Anchor link to section titled "Step 4 (optional): Creating custom abstractions"Instead of using withCache
directly in your routes, you can also create custom abstractions around it. For example, you can make your own CMS fetcher and inject it in the Remix context.
You can create as many abstractions as needed for your third-party APIs and they will be available in Remix loaders and actions. For TypeScript projects, we recommend adding types accordingly in the remix.env.d.ts
file.
Caching manually
Anchor link to section titled "Caching manually"As an alternative to the withCache
utility, you can also directly use the cache
instance that's passed to the Storefront client and available in storefront.cache
. This cache instance follows the Cache API. Using the cache instance directly is a low-level approach and you need to handle all the cases and features manually, including error handling and stale-while-revalidate.
The following example shows how to cache a request to a third-party API in Oxygen: