Oxygen Full-page cache
The full-page cache feature in Oxygen can reduce the time that's required to load page content for subsequent visits, because Oxygen can quickly serve the cached content instead of having to execute the Hydrogen storefront worker to generate a response. This results in a faster and more responsive user experience, which can lead to increased conversions.
This guide provides an introduction to the full-page cache feature, including its benefits and how it works.
Anchor to How it worksHow it works
The full-page cache feature in Oxygen helps you optimize the performance of Hydrogen storefronts by caching the generated response from your Hydrogen storefront worker. This is typically an HTML page.
Full-page cache works by intercepting incoming requests and checking if a cached version of the requested content is available. This check for the cached version can have the following outcomes, depending on its state:
- If a cached version is found and it's not stale, then the cached content is served to the user. No request is made to the Hydrogen storefront worker.
- If a cached version is found and it is stale, then the cached content is served to the user. The Hydrogen storefront worker is executed in the background and Oxygen caches the response to be used for future requests.
- If a cached version isn't found, then the Hydrogen storefront worker is executed for that request, and Oxygen caches the response to be used for future requests.
Anchor to Caching criteriaCaching criteria
For Oxygen to consider a response from a Hydrogen storefront worker execution as cacheable, the response must meet the following criteria:
- Be a response to a
GETrequest - Have a
2XXor3XXstatus code. - Have a
publicOxygen-Cache-Controlheader set with a non zeromax-age, ors-maxage, value. - Have a
Varyheader set with a value to indicate what requests can be served using the cached response.
If a Hydrogen storefront worker's response was generated with server-side personalization, for example a serialized cart session, this might result in Oxygen serving a seemingly outdated cached response, or serving the same cart session to multiple users. It's your responsibility to ensure that pages opted into Oxygen's full-page cache can be served for requests with the same path, method, and request headers as specified by Vary.
If a Hydrogen storefront worker's response was generated with server-side personalization, for example a serialized cart session, this might result in Oxygen serving a seemingly outdated cached response, or serving the same cart session to multiple users. It's your responsibility to ensure that pages opted into Oxygen's full-page cache can be served for requests with the same path, method, and request headers as specified by Vary.
Anchor to [object Object], response headerOxygen-Cache-Control response header
Oxygen-Cache-Control response headerFull-page cache relies on the Oxygen-Cache-Control header that's returned in Hydrogen storefront worker responses to determine if a response can be cached and for how long.
Set the Oxygen-Cache-Control header to public for responses that can be cached, and include a max-age directive in the header to specify the maximum amount of time that the response can be cached. This header is sent in the client response.
The following table describes the supported Oxygen-Cache-Control response headers that you can use in Oxygen, and provides some examples of each header directive that can be used to control cache behavior:
| Header directive | Description | Example usage |
|---|---|---|
public | Indicates that the response can be cached by any cache. | Oxygen-Cache-Control: public |
max-age | Specifies the maximum amount of time, in seconds, that the response can be cached. | Oxygen-Cache-Control: public, max-age=3600 |
s-maxage | Specifies the maximum amount of time, in seconds, that the response can be cached by shared caches. | Oxygen-Cache-Control: public, s-maxage=7200 |
stale-while-revalidate | Indicates that the cache can serve stale content while it fetches a fresh version in the background. | Oxygen-Cache-Control: public, max-age=3600, stale-while-revalidate=600 |
Anchor to [object Object], response headerVary response header
Vary response headerOxygen uses the Vary response header to determine which incoming request headers should be used when looking for a cached response for the requested path.
When a Hydrogen storefront worker sets a Vary response header, Oxygen will respect it.
For example, if a Hydrogen storefront worker returns a Vary: Accept-Encoding, then Oxygen serves the same cached response for every incoming request for a particular path with the same Accept-Encoding request header value.
By default, Hydrogen storefront workers don't return a Vary response header. You need to decide what's best based on your implementation. A good default is Accept-Encoding, Accept-Language.
By default, Hydrogen storefront workers don't return a Vary response header. You need to decide what's best based on your implementation. A good default is Accept-Encoding, Accept-Language.
Anchor to [object Object], client response headerOxygen-Full-Page-Cache client response header
Oxygen-Full-Page-Cache client response headerThe Oxygen-Full-Page-Cache header is an informational response header that's always returned by Oxygen to clients. It's used to help developers debug and understand the cache status of a response in a full-page cache implementation. The header has the following possible values, which each indicate a different cache status:
| Header value | Description |
|---|---|
Miss | The requested resource wasn't found in the cache, and a new response was generated. This occurs when the cache doesn't have a matching entry for the requested path, and the response is generated by the Hydrogen storefront worker. |
Hit | The requested resource was found in the cache, and the cached response is still up to date. This occurs when the cache has a matching entry for the requested path, and the response isn't stale according to the cache's max-age, which is specified in the Oxygen-Cache-Control response header. |
Stale | The requested resource was found in the cache, but the cached response is stale. This occurs when the cache has a matching entry for the request, but the response is considered stale according to the cache's max-age, which is specified in the Oxygen-Cache-Control response header. In this case, the stale response is served, and a request is made to the Hydrogen storefront worker to asynchronously update the cache with a new response. |
Uncacheable | The requested resource can't be cached by Oxygen. This occurs in the following scenarios:
|
Anchor to LimitationsLimitations
Full-page cache is designed to work with Hydrogen storefront workers and has the following limitations:
- You can't purge Oxygen's full page cache for the currently deployed worker. You either need to wait for the cached response to expire, or make a new deployment of your Hydrogen storefront worker to start with a fresh cache.
- Oxygen won't be able to serve a cached response from a previous deployment on a new deployment.
- The headers specified for
Varywill use those header(s) complete values. There is no way to use only specific cookies, for example.