RFC: Hydrogen Caching

[blittle]

You can improve performance by caching either the full page of a request, or some of the individual queries that go into rendering a page. For example, the entire page /products/hydrogen can be cached, and every customer is served that cached page. Alternatively, the full page is re-rendered for every customer, but the underlying queries to the Storefront API and other third-party APIs are cached. Full-page caching isn’t appropriate for personalized or dynamic experiences, because the server rendered page needs to be different per user.

Hydrogen v1 supports both forms of caching. This RFC explores how we can expand that support to v2.

Sub-request Caching

Hydrogen v2 only supports caching sub-requests to the Storefront API via our storefront client. If you need to make an API request to a third party API, we have recommended to directly use the cache API of whatever platform you deploy to. For example, an implementation using the cache API on Oxygen might look like:

export async function loader() {
  const response = await fetchWithCache("https://www.some-api.com/api");
  const data = await response.json();
  return json(data);
}

async function fetchWithCache(url, cacheControl) {
  const cache = caches.open('your-app');
  const subRequestUrl = new URL(url);
  const cacheKey = new Request(subRequestUrl.toString());
  let response = await cache.match(cacheKey);

  if (!response) {
    // Response not present within cache
    response = await fetch(request);
    response = new Response(response.body, response);
    response.headers.append("Cache-Control", cacheControl);
    ctx.waitUntil(cache.put(cacheKey, response.clone()));
  }

  return response;
}

The problem is that the cache API is complex. The above example also does not work with POST requests. Caching POSTs gets much more complex. It also has no stale-while-revalidate. We think we can do better.

We propose a new withCache utility that you can inject into your action/loader context:

export async function loader({context: {withCache}}: LoaderArgs) {
  await withCache(
    ['some', 'key'],
    async () => console.log('this should only show up once every 10 secs'),
    {
      strategy: storefront.CacheCustom({
        mode: 'public',
        maxAge: 10,
      }),
    },
  );

Track this proposal at: #600

Full-page caching

Hydrogen v1 supports full-page caching. Remix encourages developers to use Cache-Control headers. Those headers will be respected by the browser, so that a single browser won’t request the same page more than once. But separate browsers still make duplicate requests without caching on the server/worker.

We propose full-page caching as a feature available on Oxygen. Seamlessly using the Oxygen remix adapter, any Cache-Control headers returned from both your loaders or pages, will result in caching at the edge.

Track this proposal at: #615

Caching off Oxygen

Different platforms (Netlify, Vercel, Cloudflare, Deno, etc) offer different caching solutions. Hydrogen works best when deployed to Oxygen, because we can automatically setup everything for you. But if you want storefront.query to cache properly on other platforms, you need to build your own Cache implementation, and pass an instance to createStorefrontClient:

import {redis} from 'some-3p-redis-client';

class YourCache implements Cache {
  async function get(key: string) {
    // return await redis.get(key);
  }

  async function set(key: string, value: string) {
    // return await redis.set(key, value);
  }

  // ...
}

const cache = new YourCache();

// Make sure to pass your custom cache instance to `createStorefrontClient`
const {storefront} = createStorefrontClient({
  cache,
  ...
});

const handleRequest = createRequestHandler({
  getLoadContext: () => ({ storefront }),
  ...
});

[juanpprieto]

Re: Sub-request Caching

I feel it's a little confusing that the caching strategy helper CacheCustom is a storefront method while withCache is a top-level method.

export async function loader({context: {withCache}}: LoaderArgs) {
  await withCache(
    ['some', 'key'],
    async () => console.log('this should only show up once every 10 secs'),
    {
      strategy: storefront.CacheCustom({
        mode: 'public',
        maxAge: 10,
      }),
    },
  );

Should both CacheCustom and withCache helpers belong to a more generic cache object?

// Example property names that came to mind
const cache = {
  fn, // withCache
  strategy // storefront.CacheCustom
}

In practice it would look like this:

export async function loader({context: {cache}}: LoaderArgs) {
  await cache.fn(
    ['some', 'key'],
    async () => console.log('this should only show up once every 10 secs'),
    {
      strategy: cache.strategy({
        mode: 'public',
        maxAge: 10,
      }),
    },
  );

[maxshirshin]

Oxygen has backported the Hydrogen's implementation with some minor adjustments and we're ready to give it to select merchants:
https://github.com/Shopify/oxygen-workers/pull/705

Additionally, we are discussing how Oxygen could help users benefit from unique features, namely:

• Cache usage monitoring: we can collect and post-process caching data
• Cache purging: there's a CF-specific API which we can utilise in Oxygen to purge Cache API entries selectively

I'll link the corresponding issues once we have them available.

Meanwhile, Oxygen wants to align with Hydrogen on how we could test it.

[chaitapcart]

Is there a timeline on when it will be available to all merchants? If not, how can we go about requesting this feature for a specific merchant?

Looking mostly at the cache purging specific entries/routes

[maxshirshin]

Hi @chaitapcart no specific date yet. Could you please elaborate on what you'd like to have in terms of features? and why purging would be important, and what are your expectations for that feature? Thanks!

[thomasKn]

Any chance the full page caching will be supported in V2?
I'm trying to cache ressource routes responses at the CDN level but I always get the uncacheable header:

[jamalsoueidan]

I'm still getting the same response... This is _index.tsx inside routes

return json(
    {
    ...
    },
    {
      headers: {
        'Cache-Control': 'public, s-maxage=3600, stale-while-revalidate=3600',
      },
    },
  );

The page is fast, but I wonder when we cache _index, how it works? since it's not full page cache, only when we cache root.tsx, and nobody will do that, since their is login button and such on the frontpage, we need to do those request in the client instead to be able to cache full page?