HTML Page Cache

What is HTML page caching?

deco caches the full HTML response at the CDN edge for eligible pages. Instead of every request traveling to the origin server, the edge node returns a previously cached page response — reducing latency and origin load.

How to enable

HTML page caching is available to all VTEX sites on deco. To enable it, update your dependencies to the minimum required versions:

Update your deno.json or run:

 deno task update 

That’s it. No environment variables or manual configuration needed.

What gets cached

Only public, anonymous page requests are eligible:

• Visitors who are not logged in
• Pages with no active personalized segment (no active campaigns, price tables, or region-specific pricing)
• Standard page navigation requests

What is never cached

The following always bypass the HTML cache and are served fresh from the origin:

Cache lifetime

The default Cache-Control value is:

 public, max-age=90, s-maxage=90, stale-while-revalidate=3600, stale-if-error=86400 

This means:

• Cached responses are served for 90 seconds, after which the next request fetches a fresh response from the origin.
• A 1-hour stale-while-revalidate window: stale responses are served immediately while a fresh response is fetched in the background.
• A 24-hour stale-if-error window: stale responses are served if the origin returns an error.

To use a custom value, set the DECO_PAGE_CACHE_CONTROL environment variable in your site’s configuration.

Note: If your application already sets a Cache-Control header on a response, that value is used as-is and the platform default is ignored.

How to verify

Inspect the Cache-Control response header to confirm a page is eligible for HTML caching:

 curl -sI https://www.yoursite.com/ | grep -i cache-control 

Expected output for an anonymous (cacheable) request:

 cache-control: public, max-age=90, s-maxage=90, stale-while-revalidate=3600, stale-if-error=86400 

Expected output for a non-cacheable request (e.g., a logged-in user):

 cache-control: no-store, no-cache, must-revalidate 

Interaction with other caching layers

HTML page caching works alongside other caching mechanisms in deco:

• Loader cache: Caches data fetched by loaders at the server level. When an HTML page cache hit occurs, the origin is not reached at all — loaders do not run.
• Stale Edge Cache (async sections): Caches individual lazy-loaded sections at the CDN. HTML page caching operates at the full assembled page level, one layer above.

A CDN-level HTML cache hit means the page is served entirely from the edge, with no server involvement.

Limitations

• No manual cache purge: There is currently no way to manually invalidate cached HTML responses. Cached pages expire naturally after the TTL window.

Implementation

The caching logic lives in the deco runtime, open source at github.com/deco-cx/deco.

See also

• Caching data loaders
• Edge Async Render