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:

Example

Anchor link to section titled "Example"

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: `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 the `max-age` time expires.
`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: