Configuring GraphQL cache control for `GET` requests

This is an experimental feature.

This guide explains how to configure caching for GraphQL GET requests using the graphqlCacheControl flag. Setting cache rules allows responses to be stored and reused for subsequent requests, reducing server load and improving store performance. For example, caching a product listing page (such as "Summer Collection") for five minutes allows the page to load faster for store visitors. The system serves cached content immediately, then updates it in the background, ensuring fresh results without slowing down the user experience, improving performance, and minimizing additional server load.

The graphqlCacheControl flag defines how long responses should be stored and reused by configuring caching for GraphQL GET requests.

POST requests are excluded from caching by default. This ensures that data sent in the request body, such as user inputs or sensitive information, is always processed in real time and not served from the cache.

Before you begin

Ensure that your project is using the latest version of the @faststore/cli package. To do so, follow the instructions in Updating the '@faststore/cli' package version.

Instructions

Since the graphqlCacheControl flag is an experimental feature, declare it under the experimental section of discovery.config.js file.

Open your FastStore project in a code editor.
Open the discovery.config.js file.
Under the experimental section, add the graphqlCacheControl flag:

discovery.config.js
_10experimental: { _10 … _10 graphqlCacheControl: {}, _10},

Inside the graphqlCacheControl flag, add the maxAge and staleWhileRevalidate objects and their values:

discovery.config.js


_10experimental: {
_10    …
_10    graphqlCacheControl: {
_10    maxAge: 5 * 60, // 0 disables cache, 5 * 60 enable cache control maxAge 5 minutes
_10    staleWhileRevalidate: 60,
_10    },
_10},

For the example above the maxAge and staleWhileRevalidate objects received the following values:

Object	Description
`maxAge: 5 * 60`	Refers to the time of a response stays fresh in cache. Responses are cached for 5 minutes (300 seconds). After 5 minutes, the cache is considered `stale`. `maxAge: 0` - The `0` value would disable caching entirely.
`staleWhileRevalidate: 60`	Refers to the time of stale cache can be used while new data fetches in the background. After the initial 5 minutes (when `maxAge expires`), stale cached data can still be served for up to 1 extra minute (60 seconds) while the system fetches fresh data in the background. This ensures users see slightly older data (for 1 minute maximum) instead of waiting for a full reload.

This configuration creates a tiered caching system that balances immediate performance with data freshness. See in the table below what happens over time:

Object	Cache state	Behavior
0s - 300s	Fresh	Serves cached responses instantly. No backend requests unless it's the first request.
300 s - 360 s	Stale	Serves old data while fetching updates. Simultaneously fetches fresh data in background.
After 360 s	Expired	Cache fully expires. Next request triggers a fresh data fetch.

Open a terminal and run yarn dev to sync the changes and start testing cache configuration.

Testing the cache configuration

After enabling the graphqlCacheControl flag in discovery.config.js and running yarn dev in a terminal, follow these steps to test the cache configuration:

Open the localhost path available in the terminal to see the store preview (e.g., http://localhost:3000/).
On the store preview page, open your browser's Developer Tools.
Go to the Network tab and look for the Cache-Control column as the image below:
${"base64":" ","img":{"width":1919,"height":638,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":616022,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/graphql-cache-control-flag-localhost___70d2f2c3fbf40846180c7c0ed11d16f0.png"}}$