SSR, hydration e @defer sem chute

Transforme renderização em decisão por rota#

Comece um nível abaixo de "o app deve usar SSR?" Pergunte quais rotas precisam de qual modo de renderização. Pricing, artigo de blog, dashboard logado e checkout não têm as mesmas restrições.

A configuração de server routes do Angular dá ao time um lugar para registrar essa decisão no código. Isso importa porque estratégia de renderização precisa sobreviver ao code review, não sumir em notas de reunião.

Em rotas parametrizadas com prerender, mantenha chamadas de inject() antes de qualquer await dentro de getPrerenderParams. Isso mantém o exemplo alinhado com a regra de contexto de injeção síncrono do Angular.

// app.routes.server.ts
import { inject } from '@angular/core';
import { RenderMode, ServerRoute } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: '',
    renderMode: RenderMode.Prerender,
  },
  {
    path: 'pricing',
    renderMode: RenderMode.Prerender,
  },
  {
    path: 'blog/:slug',
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      const posts = inject(PostCatalog);
      const slugs = await posts.publicSlugs();
      return slugs.map((slug) => ({ slug }));
    },
  },
  {
    path: 'app/**',
    renderMode: RenderMode.Client,
  },
  {
    path: 'checkout',
    renderMode: RenderMode.Server,
  },
  {
    path: '**',
    renderMode: RenderMode.Server,
  },
];

Hydration é contrato, não interruptor#

Hydration só funciona quando o DOM do servidor e o DOM do cliente concordam. DOM manual, HTML inválido, rewrites de CDN e pressupostos de browser não são detalhe pequeno. São motivos para uma página renderizada no servidor falhar quando o cliente tenta reaproveitar o HTML existente.

Habilite hydration com event replay em rotas públicas onde interação cedo importa, e deixe a política de transfer cache explícita. Endpoints específicos de usuário não deveriam virar dados reaproveitáveis no HTML inicial por acidente.

Em setups SSR customizados, o provider de hydration também precisa entrar na configuração de bootstrap do servidor. Caso contrário, cliente e servidor não estão seguindo o mesmo contrato de renderização.

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import {
  provideClientHydration,
  withEventReplay,
  withHttpTransferCacheOptions,
} from '@angular/platform-browser';

export const appConfig: ApplicationConfig = {
  providers: [
    provideClientHydration(
      withEventReplay(),
      withHttpTransferCacheOptions({
        filter: (req) => !req.url.includes('/api/profile'),
        includeRequestsWithAuthHeaders: false,
      })
    ),
  ],
};

`@defer` deve tirar JavaScript real do caminho inicial#

@defer não é estado de loading decorativo. Ele merece entrar quando uma dependência standalone é pesada o suficiente para que adiar seu carregamento melhore o caminho inicial ou o caminho de interação.

Revise o diff com três perguntas: qual componente sai do bundle inicial, qual placeholder evita layout shift e o que acontece se o código deferido falhar ao carregar?

Os blocos de placeholder, loading e error são carregados de forma eager, então mantenha esses blocos baratos. E em SSR ou SSG, um @defer normal renderiza o placeholder no servidor; se o conteúdo principal precisa renderizar no servidor, a conversa passa para incremental hydration.

<section
  class="report-route"
  aria-live="polite"
  aria-atomic="true"
>
  <app-report-summary [summary]="summary()" />

  @defer (on viewport; prefetch on idle) {
    <app-revenue-chart [series]="series()" />
  } @placeholder (minimum 600ms) {
    <app-chart-skeleton aria-label="Chart loading" />
  } @loading (after 200ms; minimum 600ms) {
    <app-chart-skeleton aria-label="Chart loading" />
  } @error {
    <app-inline-error message="Could not load the chart" />
  }
</section>

Incremental hydration é para ilhas com motivo#

Incremental hydration mantém conteúdo renderizado no servidor visível enquanto atrasa a hidratação de seções escolhidas. Isso faz sentido para seções caras que não precisam estar interativas imediatamente.

Não faça disso a primeira tarefa de SSR em um app maduro. Primeiro prove que a hydration normal está limpa, depois teste uma rota onde uma ilha cara tem ganho visível. O Angular habilita event replay automaticamente com incremental hydration, então o time também precisa testar cliques e teclado antes da hidratação.

// main.ts
bootstrapApplication(AppComponent, {
  providers: [
    provideClientHydration(withIncrementalHydration()),
  ],
});

@defer (hydrate on viewport) {
  <app-revenue-chart [series]="series()" />
} @placeholder {
  <app-chart-skeleton aria-label="Chart loading" />
}

Mova DOM browser-only para fora da renderização#

SSR expõe código que assume window, document, medição de layout ou biblioteca de chart disponível durante renderização. Evite transformar isso em branches de isPlatformBrowser espalhados pelo template.

Para trabalho de DOM que só faz sentido no browser, use hooks como afterNextRender. O HTML renderizado continua consistente, e o side effect browser-only roda depois que o Angular renderizou no browser.

export class ChartHostComponent {
  private readonly chartHost = viewChild.required<ElementRef>('chartHost');

  constructor() {
    afterNextRender(() => {
      const width = this.chartHost().nativeElement.clientWidth;
      this.resizeChart(width);
    });
  }

  private resizeChart(width: number) {
    // browser-only chart API
  }
}

O spike deve gerar números e exceções#

Mudanças de renderização podem soar maiores do que a evidência. Mantenha o spike estreito: medir o estado atual, mudar uma rota ou um componente pesado, e registrar o que melhorou, o que quebrou e o que precisou ser pulado.

ngSkipHydration pode ser uma exceção tática para um componente legado que muta DOM, mas precisa ter nome do componente, motivo, responsável e plano de remoção. Se a lista de exceções cresce, hydration está mostrando algo sobre a codebase.

rm -rf dist .angular/cache
time npx ng build --configuration production --stats-json
npx ng test --no-watch
npx lighthouse https://staging.example.com/critical-route --only-categories=performance