O framework Astro consagrou-se pela entrega de páginas leves usando sua arquitetura de ilhas nativas e carregamento seletivo de JavaScript. Com o lançamento do Astro 7.0, o controle de renderização híbrida foi aprimorado, permitindo mesclar geração estática (SSG) com rotas dinâmicas renderizadas no servidor (SSR) de forma transparente.
Neste guia, mostramos como configurar a renderização híbrida no seu projeto para obter o melhor resultado de indexação de SEO e performance nos Core Web Vitals.
O Que É Renderização Híbrida no Astro?
Por padrão, o Astro gera todas as páginas como estáticas no momento do build (SSG). Ao ativar o modo híbrido em seu arquivo de configuração, você diz ao Astro que a maioria das páginas continuará estática, mas algumas páginas específicas serão geradas sob demanda no servidor (SSR) quando o usuário as solicitar.
Isso é ideal para blogs ou e-commerces que possuem páginas estáticas de alta velocidade, mas necessitam de rotas de pesquisa em tempo real, painéis de usuário ou carrinhos dinâmicos.
Configuração do Modo Híbrido
No seu arquivo astro.config.mjs, você deve habilitar o adaptador do servidor correspondente (como Vercel, Netlify ou Node) e definir o modo como hybrid:
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';
export default defineConfig({
output: 'hybrid',
adapter: vercel(),
});Definindo o Tipo de Renderização por Rota
Uma vez configurado o modo híbrido na raiz, todas as páginas em src/pages/ serão tratadas como SSG (estáticas).
Para tornar uma rota específica dinâmica (SSR), basta adicionar a linha de exportação prerender = false no topo do frontmatter do arquivo .astro ou .ts:
---
// src/pages/pesquisa.astro
// Força esta página específica a rodar no servidor sob demanda
export const prerender = false;
const query = Astro.url.searchParams.get('q') || '';
// Executa lógica de banco de dados dinâmica aqui...
---
<Layout title="Pesquisa">
<h1>Resultados para: {query}</h1>
</Layout>Se você precisar fazer o oposto em um projeto configurado como totalmente SSR (output: 'server'), adicione export const prerender = true no topo das rotas que deseja converter em arquivos estáticos (SSG).
Benefícios nos Core Web Vitals
A renderização híbrida garante que suas principais páginas de pouso (Landing Pages e Posts de Blog) atinjam notas máximas de LCP (Largest Contentful Paint) e CLS (Cumulative Layout Shift), já que o navegador recebe apenas arquivos HTML estáticos puros e sem atrasos de processamento no servidor.