Capítulo 67 de 456

PPR Platform Guide

Core Idea

Guide for platform/adapter engineers implementing Partial Prerendering (PPR) support: how to store the static shell + postponedState pair, serve them, and trigger the resume protocol to render only the dynamic portions.

Key Concepts

  • Static HTML shell: prerendered content with Suspense fallbacks where dynamic content will go, produced at build time for each PPR route.
  • postponedState: opaque serialized string produced alongside the shell; must be stored/updated atomically with it and never parsed or modified.
  • RSC payload: also produced at build time for the static portions.
  • Resume protocol: tells the Next.js handler to skip the shell and render only deferred Suspense boundaries, using the stored postponedState.
  • requestMeta.onCacheEntryV2: adapter hook to observe cache updates (shell + postponedState pairs) and propagate them to storage after revalidation.
  • renderingMode: 'PARTIALLY_STATIC': marker in the adapter build output (outputs.prerenders) identifying PPR routes; read fallback.postponedState from those entries.

Code Examples

POST /route
Headers: next-resume: 1
Body: <postponedState blob>
  • O que demonstra: protocolo CDN-para-origem para retomar a renderização dinâmica de uma rota PPR.
requestMeta: { postponed: postponedState }
  • O que demonstra: terceiro argumento equivalente ao header next-resume: 1 + body, quando o handler é chamado diretamente (adapter-based), sem round-trip HTTP.

Reference Tables

Implementation levelHow it works
Origin-onlyTodas as requisições vão direto ao servidor Next.js; ele lê o shell do cache local e faz stream do dinâmico. Funciona em qualquer plataforma com streaming HTTP.
CDN Shell + Origin ComputeCDN serve o shell do edge, envia request de resume para a origem (em paralelo), origem renderiza só o dinâmico, CDN concatena tudo num stream único.

Anti-patterns

  • Servir um shell novo com um postponedState antigo (ou vice-versa): produz conteúdo dinâmico incorreto; os dois artefatos precisam ser atualizados atomicamente.
  • Parsear ou alterar postponedState: é opaco por design; qualquer modificação quebra a renderização.

Key Takeaways

  1. PPR sempre produz dois artefatos por rota (shell + postponedState) que devem ser tratados como uma unidade atômica.
  2. next start já implementa o caso "origin-only" automaticamente, sem infraestrutura extra.
  3. Para menor TTFB, o shell pode vir de um KV store no edge, populado em onBuildComplete.
  4. Se o postponedState estiver indisponível ou obsoleto, faça fallback para render completo no servidor (degradação graciosa).
  5. Numa combinação Server Action + resume PPR, o header x-next-resume-state-length separa o prefixo do postponed state do corpo da action.

Connects To

  • Implementing PPR in an Adapter (api-reference/adapters): referência completa de API e exemplos de código do adapter.
  • Rendering Philosophy / Streaming: base conceitual de como estático e dinâmico coexistem numa rota.
AnteriorPackage BundlingPróximoPrefetching