Fresh archive: HTML Page Cache

Documentação de produto descontinuado — Fresh e o antigo admin foram descontinuados. Estas instruções são mantidas para migração e referência histórica. Novos projetos usam Blocks 7.x e o Editor de Sites do Studio.

Esta página ainda não foi traduzida para o português — o conteúdo abaixo está em inglês.

Retired Fresh / Deno reference. This original guide preserves the earlier runtime APIs, Preact/HTMX examples, and any former admin steps. Use it when maintaining that runtime; consult the Studio Site Editor guides for current editing. Migration notes distinguish editor and framework migration.

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:

Package	Minimum version
`deco`	`1.199.0`
`apps`	`0.153.0`

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:

Scenario	Reason
Logged-in users	Auth session detected — response is personalized
Responses that set cookies	`Set-Cookie` present — response contains per-user state
Pages with active non-cacheable A/B flags	Variant requires per-user targeting
VTEX: users with active campaigns, price tables, or region-specific pricing	Segment is personalized — response would differ per user

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.