Cache de HTML de Página

O que é o cache de HTML de página?

A deco cacheia o HTML completo da página no edge da CDN para páginas elegíveis. Em vez de toda requisição percorrer o caminho até o servidor de origem, o nó de edge retorna uma resposta de página previamente cacheada — reduzindo latência e carga no servidor de origem.

Como habilitar

O cache de HTML está disponível para todos os sites VTEX na deco. Para habilitar, atualize as dependências para as versões mínimas necessárias:

Pacote	Versão mínima
`deco`	`1.199.0`
`apps`	`0.153.0`

Atualize seu deno.json ou execute:

 deno task update

Só isso. Nenhuma variável de ambiente ou configuração manual necessária.

O que é cacheado

Apenas requisições de página públicas e anônimas são elegíveis:

Visitantes que não estão logados
Páginas sem segmento personalizado ativo (sem campanhas, tabelas de preço ou pricing por região ativos)
Requisições de navegação de página comuns

O que nunca é cacheado

Os casos a seguir sempre ignoram o cache de HTML e são servidos diretamente da origem:

Cenário	Motivo
Usuários logados	Sessão de autenticação detectada — resposta é personalizada
Respostas que definem cookies	`Set-Cookie` presente — resposta contém estado por usuário
Páginas com flags de A/B não-cacheáveis ativas	Variante requer segmentação por usuário
VTEX: usuários com campanhas ativas, tabelas de preço ou pricing por região	Segmento é personalizado — resposta diferiria por usuário

Tempo de vida do cache

O valor padrão de Cache-Control é:

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

Isso significa:

Respostas cacheadas são servidas por 90 segundos. Após esse período, a próxima requisição busca uma resposta atualizada da origem.
Uma janela de stale-while-revalidate de 1 hora: respostas expiradas são servidas imediatamente enquanto uma resposta atualizada é buscada em segundo plano.
Uma janela de stale-if-error de 24 horas: respostas expiradas são servidas se o servidor de origem retornar um erro.

Para usar um valor customizado, defina a variável de ambiente DECO_PAGE_CACHE_CONTROL na configuração do seu site.

Nota: Se a sua aplicação já define um header Cache-Control na resposta, esse valor é usado como está e o padrão da plataforma é ignorado.

Como verificar

Inspecione o header Cache-Control da resposta para confirmar que uma página é elegível para o cache de HTML:

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

Saída esperada para uma requisição anônima (cacheável):

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

Saída esperada para uma requisição não cacheável (ex: usuário logado):

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

Interação com outras camadas de cache

O cache de HTML de página funciona junto com os outros mecanismos de cache da deco:

Cache de loaders: Cacheia dados buscados pelos loaders no nível do servidor. Quando ocorre um cache hit de HTML, a origem não é acessada — os loaders não executam.
Stale Edge Cache (seções assíncronas): Cacheia seções lazy-loaded individualmente na CDN. O cache de HTML de página opera no nível da página completa montada, uma camada acima.

Um cache hit de HTML no nível da CDN significa que a página é servida inteiramente do edge, sem envolver o servidor de origem.

Limitações

Sem purge manual: atualmente não há como invalidar manualmente respostas HTML cacheadas. As páginas expiram naturalmente após o TTL.

Implementação

A lógica de cache está no runtime da deco, open source em github.com/deco-cx/deco.