Guia completo de Astro SSR: ative a renderização no servidor em 3 passos

Seu blog em Astro está voando, com uma pontuação Lighthouse acima de 95, e você está satisfeito até que alguém pede: “Vamos adicionar login de usuários”. Nesse momento surge a dúvida: como implementar login em um site estático? Ao abrir a documentação oficial, você encontra uma avalanche de conceitos como SSR, SSG, Hybrid e adapter, e tudo parece cada vez mais confuso.

Foi exatamente assim quando tive meu primeiro contato com Astro SSR. Afinal, o principal atrativo do Astro é a velocidade. Adicionar renderização no servidor não deixaria o site mais lento? Entre tantos adaptadores para Vercel, Netlify e Node.js, qual escolher? E o que significam opções como output e prerender no arquivo de configuração?

Na verdade, configurar Astro SSR não é tão complicado quanto parece. Neste artigo, vou explicar da forma mais direta possível quando SSR é realmente necessário — em vez de continuar usando SSG —, como configurar rapidamente diferentes adaptadores e como combinar SSR e SSG em um mesmo projeto com o modo Hybrid. Ao final, você conseguirá decidir se seu projeto precisa de SSR e fazer a configuração em 30 minutos.

Capítulo 1: conceitos básicos de SSR e escolha técnica

Quando usar SSR em vez de SSG?

Comece com o critério mais simples: o conteúdo já está definido no momento do build ou pode mudar a cada acesso?

SSG (Static Site Generation, ou geração de site estático) é como um prato feito preparado com antecedência. O cozinheiro deixa tudo pronto pela manhã e, quando o cliente chega, basta servir: é muito rápido. Posts de blog, páginas de produto e a página Sobre quase não mudam, por isso SSG funciona perfeitamente nesses casos.

SSR (Server-Side Rendering, ou renderização no servidor) é como um prato preparado na hora. O cliente faz o pedido e o cozinheiro prepara a refeição conforme a necessidade dele. Uma mensagem como “Bem-vindo de volta, João” depois do login, a cotação de uma ação em tempo real ou a quantidade de itens no carrinho variam de pessoa para pessoa e exigem SSR.

Talvez você ainda esteja se perguntando se seu projeto realmente precisa de SSR. Se uma destas cinco situações fizer parte dele, vale considerar essa opção:

1. Autenticação de usuários e conteúdo personalizado

O exemplo mais comum é o login. Não há como saber durante o build quem entrará no sistema nem qual nome deve aparecer. Em uma plataforma de cursos que desenvolvi, por exemplo, a página inicial precisava mostrar “Continue aprendendo: aula 5”. Isso exige SSR para gerar o conteúdo dinamicamente conforme o progresso do usuário conectado.

2. Exibição de dados em tempo real

Previsão do tempo, cotações e placares esportivos mudam a cada minuto. Não faz sentido reconstruir o site a cada minuto. Com SSR, os dados mais recentes são buscados sempre que o usuário acessa a página.

3. Consultas ao banco de dados

Em uma pesquisa de produtos de e-commerce, cada termo produz resultados diferentes. É impossível gerar antecipadamente páginas para todas as pesquisas possíveis. Com SSR, o banco de dados é consultado em tempo real quando o usuário pesquisa e os resultados são retornados.

4. Rotas de API

Envio de formulários, upload de arquivos e chamadas a APIs de terceiros exigem lógica de backend. O modo SSR do Astro permite criar rotas de API em src/pages/api/xxx.js, sem a necessidade de montar um servidor de backend separado.

5. Testes A/B e recomendações personalizadas

É possível exibir conteúdo diferente conforme a localização, o horário de acesso ou o comportamento anterior do usuário. Na página inicial de um e-commerce como o Taobao, por exemplo, cada pessoa vê produtos recomendados diferentes. Esse tipo de personalização exige SSR.

Nesse ponto, alguém pode perguntar: “Posso usar SSR na página de um post do blog?”. Pode, mas não é necessário. O conteúdo do post é fixo; com SSG, um HTML estático é gerado e servido diretamente pela CDN, o que oferece mais velocidade e menor custo de servidor. SSR não resolve tudo, portanto não o use apenas por usar.

Modo Hybrid: o melhor dos dois mundos

O modo Hybrid introduzido no Astro 2.0 foi uma ideia inteligente: no mesmo projeto, páginas estáticas usam SSG e páginas dinâmicas usam SSR. Em um e-commerce, por exemplo:

• Página inicial, página Sobre e documentação de ajuda → SSG (carregamento rápido)
• Página de login, área do usuário e carrinho → SSR (conteúdo dinâmico)
• Página de detalhes do produto → SSG (conteúdo fixo)
• Página de resultados de pesquisa → SSR (consulta em tempo real)

Com essa configuração, a velocidade das páginas estáticas não é afetada, enquanto os recursos dinâmicos funcionam normalmente. Um amigo usa exatamente essa estratégia em seu blog: a listagem e os posts usam SSG, a área de comentários usa SSR e a pontuação Lighthouse continua acima de 95.

Capítulo 2: primeiros passos — ative o modo SSR em 3 etapas

Configurando Astro SSR do zero com o adaptador Node.js

Depois de confirmar que o projeto precisa de SSR, podemos começar a configuração. Primeiro, vou demonstrar com o adaptador Node.js, a opção mais genérica para servidores próprios ou implantação em VPS.

Primeiro passo: instale o adaptador com um comando

O Astro oferece um comando oficial de configuração automática muito simples. Execute-o na raiz do projeto:

npx astro add node

Esse comando faz três coisas automaticamente:

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

1. Instala o pacote @astrojs/node
2. Altera o arquivo de configuração astro.config.mjs
3. Atualiza as dependências do package.json

Ao final, o terminal exibirá uma série de marcas verdes, indicando que a configuração foi concluída. Se preferir instalar manualmente, por exemplo para escolher uma versão específica, use:

npm install @astrojs/node

Em seguida, altere o arquivo de configuração manualmente, como veremos no próximo passo.

Segundo passo: altere o arquivo de configuração

Abra astro.config.mjs na raiz do projeto. Se você usou o comando de configuração automática, o arquivo já terá este conteúdo:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server', // Ativa o modo SSR
  adapter: node({
    mode: 'standalone' // Modo de servidor independente
  }),
});

Veja o que significam essas duas opções:

Configuração de output:

• 'static' (padrão): todas as páginas usam SSG e geram HTML estático
• 'server': todas as páginas usam SSR e são geradas dinamicamente a cada solicitação
• 'hybrid': SSG por padrão, com SSR ativado por página (recomendado!)

Configuração de mode:

• 'standalone': o Astro inicia um servidor Node.js independente, indicado para implantação direta
• 'middleware': gera um middleware que pode ser integrado a frameworks como Express e Koa

Eu geralmente uso standalone, porque o servidor incluído no Astro já é suficiente e dispensa integrações adicionais. Se o projeto já tiver um backend Express e você quiser incorporar o Astro a ele, use middleware.

Terceiro passo: faça o build e execute

Depois de concluir a configuração, faça o build do projeto:

npm run build

Após o build, você verá uma nova pasta server/ dentro de dist/, com o arquivo entry.mjs. Esse é o ponto de entrada do servidor SSR.

Inicie o servidor SSR:

node ./dist/server/entry.mjs

Por padrão, o serviço será iniciado em http://localhost:4321. Ao acessar o site, todas as páginas estarão usando SSR.

Depuração no ambiente de desenvolvimento

Durante o desenvolvimento, não é preciso fazer um novo build a cada alteração. Basta executar:

npm run dev

O servidor de desenvolvimento oferece suporte automático a SSR e aplica as alterações em tempo real.

Solução de problemas comuns

1. Porta ocupada: se a porta 4321 já estiver em uso, defina outra por meio de uma variável de ambiente:

   PORT=3000 node ./dist/server/entry.mjs

2. Módulo do adaptador não encontrado: confirme se @astrojs/node está instalado e execute npm install para reinstalar as dependências

3. Página 404: verifique se os arquivos em src/pages/ estão corretos; o modo SSR continua seguindo as regras de roteamento do Astro

Configurar SSR é realmente simples. Na primeira vez que fiz isso, levei menos de cinco minutos do início até o servidor funcionar. Se você implanta na Vercel ou na Netlify, os adaptadores específicos tornam o processo ainda mais simples, como veremos no próximo capítulo.

Capítulo 3: configuração dos principais adaptadores

Como escolher entre Vercel, Netlify e Cloudflare?

Se o projeto está hospedado na Vercel, Netlify ou Cloudflare, configurar SSR é ainda mais fácil. Essas plataformas têm adaptadores dedicados mantidos oficialmente pelo Astro e permitem implantação sem configuração adicional.

Adaptador da Vercel — referência em funções serverless

A Vercel é a plataforma de implantação que mais uso. A franquia gratuita é suficiente para projetos pessoais e a configuração é muito simples:

npx astro add vercel

Esse comando configura tudo automaticamente. O arquivo de configuração fica assim:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  output: 'server',
  adapter: vercel(),
});

Recurso especial da Vercel: ISR (regeneração estática incremental)

Esse recurso exclusivo da Vercel pode deixar páginas SSR tão rápidas quanto páginas SSG. Em termos simples, a página é gerada com SSR no primeiro acesso e armazenada em cache por um período. Os acessos seguintes usam o cache, e a página é gerada novamente quando ele expira.

adapter: vercel({
  isr: {
    expiration: 60, // Cache de 60 segundos
  },
}),

Em um site de notícias, por exemplo, pode ser suficiente atualizar uma página de artigo uma vez por minuto, em vez de consultar o banco de dados a cada solicitação. Com ISR, você combina a flexibilidade do SSR e a velocidade do SSG.

Processo de implantação na Vercel:

1. Configure o adaptador
2. Envie o código para o GitHub
3. Importe o projeto no painel da Vercel
4. Comando de build: npm run build (detectado automaticamente)
5. Clique para implantar e pronto

Adaptador da Netlify — especialista em Edge Functions

A Netlify também é uma plataforma de implantação popular, especialmente para sites estáticos que incluem recursos dinâmicos.

npx astro add netlify

Arquivo de configuração:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  output: 'server',
  adapter: netlify({
    edgeMiddleware: true, // Ativa o middleware de borda
  }),
});

O que é edgeMiddleware?

Em termos simples, ele executa a lógica de middleware, como autenticação e redirecionamentos, em nós de borda para reduzir o tempo de resposta. Isso é útil quando o site tem recursos relacionados à localização, como exibir idiomas diferentes conforme a região do usuário.

Configuração de redirecionamentos na Netlify

Uma facilidade da Netlify é o processamento automático de redirecionamentos. Para redirecionar /old-page para /new-page, crie um arquivo _redirects na raiz do projeto:

/old-page  /new-page  301

O redirecionamento entra em vigor automaticamente após a implantação, sem alterações no código.

Adaptador da Cloudflare — aceleração por CDN global

Se seus usuários estão espalhados pelo mundo, a Cloudflare é uma excelente escolha. Seus Workers são executados em mais de 300 data centers no mundo inteiro, com latência muito baixa.

npx astro add cloudflare

Arquivo de configuração:

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

// astro.config.mjs
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
});

Limitações da Cloudflare

Vale lembrar que o ambiente do Cloudflare Workers não é idêntico ao Node.js. Algumas APIs do Node.js, como o sistema de arquivos fs, não estão disponíveis. Se o projeto depende dessas APIs, a Cloudflare talvez não seja adequada.

Comparação entre adaptadores

Minha recomendação:

• Blogs e documentação: priorize Vercel ou Netlify; a franquia gratuita costuma ser suficiente e a implantação é simples
• E-commerce e aplicações SaaS: Vercel, aproveitando ISR, ou um servidor Node.js próprio para ter controle total
• Produtos internacionais: Cloudflare, pela aceleração global
• Projetos corporativos: servidor Node.js próprio, por privacidade de dados e controle total

Não existe uma escolha absolutamente certa. Tudo depende das necessidades e do orçamento do projeto. Uso a Vercel no meu blog e servidores próprios nos sites corporativos de clientes; as duas opções funcionam bem em seus respectivos cenários.

Capítulo 4: modo Hybrid na prática

Use SSR e SSG no mesmo projeto

Até aqui vimos a configuração de um projeto totalmente SSR. Agora chegamos ao ponto principal: o modo Hybrid. Esse é o grande diferencial do Astro, pois permite combinar a velocidade do SSG com a flexibilidade do SSR no mesmo projeto.

Configure o modo Hybrid

Basta alterar output para 'hybrid':

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'hybrid', // SSG por padrão, SSR quando necessário
  adapter: node(),
});

Depois dessa configuração, todas as páginas usam SSG por padrão. Para ativar SSR em uma página específica, basta adicionar uma linha de código nela.

Controle a renderização em cada página

Como fazer uma página usar SSR? Adicione esta linha ao frontmatter do arquivo:

// src/pages/dashboard.astro (SSR)

---

export const prerender = false; // Desativa a pré-renderização e usa SSR
const user = Astro.cookies.get('user');

---

<h1>Bem-vindo de volta, {user?.name}</h1>
<p>Você tem {user?.notifications} notificações não lidas</p>

É só isso. prerender = false significa: “Não gere esta página durante o build; gere-a dinamicamente quando o usuário acessar”.

No caminho inverso, se output estiver definido como 'server', o que torna todas as páginas SSR, faça uma página usar SSG desta forma:

// src/pages/about.astro (SSG)

---

export const prerender = true; // Força a geração durante o build

---

<h1>Sobre nós</h1>
<p>O conteúdo desta página não muda. Ela é gerada antecipadamente e carrega muito rápido.</p>

Resumo importante para não confundir:

No começo, eu sempre invertia os dois. Depois gravei a regra: Hybrid prioriza SSG; server prioriza SSR.

Exemplo prático: blog com sistema de usuários

Imagine uma plataforma de blog com publicação de artigos e login de usuários. A configuração ideal seria:

Estrutura do projeto:

src/pages/
├── index.astro          // Página inicial (SSG)
├── about.astro          // Página Sobre (SSG)
├── blog/
│   ├── [slug].astro     // Detalhes do post (SSG)
│   └── index.astro      // Lista de posts (SSG)
├── login.astro          // Página de login (SSR)
├── dashboard.astro      // Área do usuário (SSR)
└── api/
    └── comments.js      // API de comentários (SSR)

Arquivo de configuração:

// astro.config.mjs
export default defineConfig({
  output: 'hybrid', // SSG por padrão
  adapter: vercel(), // Implantação na Vercel
});

Página estática, sem configuração especial:

// src/pages/blog/[slug].astro

---

// Sem configuração de prerender, o padrão é SSG
import { getCollection } from 'astro:content';

export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;

---

<article>
  <h1>{post.data.title}</h1>
  <div set:html={post.body} />
</article>

Página dinâmica, com SSR:

// src/pages/dashboard.astro

---

export const prerender = false; // Ativa SSR

// Verifica se o usuário está conectado
const token = Astro.cookies.get('token')?.value;
if (!token) {
  return Astro.redirect('/login');
}

// Busca as informações do usuário no banco de dados
const user = await fetch(`https://api.example.com/user`, {
  headers: { Authorization: `Bearer ${token}` }
}).then(res => res.json());

---

<div>
  <h1>Olá, {user.name}</h1>
  <p>E-mail: {user.email}</p>
  <p>Último acesso: {user.lastLogin}</p>
</div>

Rota de API, que usa SSR automaticamente:

// src/pages/api/comments.js
export async function POST({ request }) {
  const { articleId, content } = await request.json();

  // Salva o comentário no banco de dados
  await db.comments.insert({
    articleId,
    content,
    createdAt: new Date(),
  });

  return new Response(JSON.stringify({ success: true }), {
    status: 200,
    headers: { 'Content-Type': 'application/json' }
  });
}

export async function GET({ url }) {
  const articleId = url.searchParams.get('articleId');

  // Lê os comentários do banco de dados
  const comments = await db.comments.findMany({
    where: { articleId },
    orderBy: { createdAt: 'desc' }
  });

  return new Response(JSON.stringify(comments), {
    headers: { 'Content-Type': 'application/json' }
  });
}

Benefícios dessa configuração:

1. As páginas estáticas, como posts e página inicial, continuam extremamente rápidas, com pontuação Lighthouse acima de 95 e conteúdo servido pela CDN
2. Páginas dinâmicas, como a área do usuário, buscam dados em tempo real, e cada pessoa vê seu próprio conteúdo
3. Rotas de API oferecem recursos de backend sem a necessidade de montar um servidor separado
4. O tempo de build é curto, pois somente as páginas estáticas precisam ser pré-renderizadas; as páginas dinâmicas não aumentam o build

Em um projeto que desenvolvi, com 50 posts e um sistema de usuários, o build levou apenas 20 segundos. Depois da implantação, as páginas estáticas abriam instantaneamente e as dinâmicas respondiam em menos de 100 ms. O modo Hybrid é realmente uma boa prática.

Capítulo 5: problemas comuns e boas práticas

Armadilhas na configuração de SSR e como resolvê-las

Enfrentei vários problemas ao configurar SSR. A seguir, reuni os mais comuns e suas soluções para ajudar você a evitá-los.

Problema 1: erro Astro.clientAddress is only available when using output: 'server'

Causa: o código usa Astro.clientAddress para obter o IP do usuário, mas output ainda está definido como 'static'.

Solução:

// astro.config.mjs
export default defineConfig({
  output: 'server', // Ou 'hybrid'
  adapter: node(),
});

APIs dinâmicas como Astro.clientAddress, Astro.cookies e Astro.redirect() só podem ser usadas no modo SSR.

Problema 2: página 404 após a implantação, embora funcione localmente

Causa: o adaptador está configurado incorretamente, ou o comando de build e o diretório de saída da plataforma estão errados.

Solução:

Implantação na Vercel:

• Comando de build: npm run build
• Diretório de saída: .vercel/output (automático)
• Não configure rotas manualmente em vercel.json; deixe o Astro cuidar delas

Implantação na Netlify:

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

• Comando de build: npm run build
• Diretório de publicação: dist para conteúdo estático ou .netlify para SSR
• Se o erro 404 continuar, verifique netlify.toml:

  [build]
    command = "npm run build"
    publish = "dist"

Problema 3: página SSR demora mais de dois segundos para carregar

Causa: o servidor não tem desempenho suficiente, ou a consulta ao banco de dados está lenta.

Solução:

1. Use cache:

   // src/pages/api/news.js
   export async function GET() {
     const cached = await redis.get('news');
     if (cached) {
       return new Response(cached, {
         headers: {
           'Content-Type': 'application/json',
           'Cache-Control': 'public, max-age=60' // Cache de 60 segundos
         }
       });
     }
   
     const news = await fetchNewsFromDB();
     await redis.set('news', JSON.stringify(news), 'EX', 60);
   
     return new Response(JSON.stringify(news), {
       headers: {
         'Content-Type': 'application/json',
         'Cache-Control': 'public, max-age=60'
       }
     });
   }

2. Otimize as consultas ao banco de dados:

   • Adicione índices
   • Reduza o número de JOINs
   • Consulte apenas os campos necessários

3. Considere ISR, se estiver usando Vercel:

   adapter: vercel({
     isr: { expiration: 300 } // Cache de 5 minutos
   }),

Problema 4: variáveis de ambiente não estão disponíveis no cliente

Causa: no Astro, há uma diferença entre variáveis de ambiente do cliente e do servidor.

Solução:

No servidor, em páginas SSR e rotas de API:

const secret = import.meta.env.SECRET_KEY; // Qualquer variável de ambiente pode ser usada

No cliente, no JavaScript executado no navegador:

const apiUrl = import.meta.env.PUBLIC_API_URL; // O nome deve começar com PUBLIC_

Configuração do arquivo .env:

SECRET_KEY=abc123          # Disponível somente no servidor
PUBLIC_API_URL=https://api.example.com  # Disponível no cliente e no servidor

Problema 5: erro adapter.setApp is not a function

Causa: as versões do Astro e do adaptador são incompatíveis.

Solução:

# Atualize para as versões mais recentes
npm update astro @astrojs/node

# Ou instale versões compatíveis, conforme a documentação oficial
npm install astro@latest @astrojs/node@latest

Em geral, manter o Astro e o adaptador nas versões mais recentes evita esse problema.

Resumo de boas práticas

1. Use o modo Hybrid como padrão: a menos que todas as páginas precisem de SSR, output: 'hybrid' é a melhor opção
2. Ative SSR apenas quando necessário: defina prerender = false somente nas páginas que realmente exigem renderização dinâmica
3. Sirva recursos estáticos pela CDN: coloque imagens e arquivos CSS e JS no diretório public/ para que sejam entregues pela CDN sem passar pelo SSR
4. Defina uma estratégia de cache: para conteúdo dinâmico que muda pouco, como uma lista de notícias, use cache ou ISR para reduzir a carga do servidor
5. Separe as variáveis de ambiente: use variáveis do servidor para informações confidenciais e o prefixo PUBLIC_ para configurações públicas
6. Monitore o desempenho: use Vercel Analytics ou Google Analytics para acompanhar o tempo de resposta das páginas SSR e otimizá-las quando necessário

Conclusão

Depois de tudo isso, a ideia central cabe em três frases:

1. SSR não resolve tudo; use-o apenas quando necessário

Não adote SSR por empolgação nem trate SSG como ultrapassado. Use SSG em páginas estáticas e SSR em páginas dinâmicas. Para a maioria dos projetos, o modo Hybrid é o mais adequado. Já vi alguém migrar um blog inteiro para SSR e acabar com um desempenho pior; como o conteúdo dos posts não muda, SSG com CDN certamente é mais rápido.

2. Escolha o adaptador conforme a plataforma; a configuração é simples

Se você usa Vercel, Netlify ou Cloudflare, basta executar npx astro add [platform]. Em um servidor próprio, npx astro add node também leva poucos minutos. Não se assuste com a documentação: na prática, a configuração é muito mais simples do que parece.

3. O modo Hybrid oferece o melhor dos dois mundos

Essa é a essência do Astro. As páginas estáticas mantêm uma pontuação Lighthouse acima de 95, as páginas dinâmicas oferecem recursos personalizados, o tempo de build não aumenta e os custos de servidor não disparam. Hoje, o modo Hybrid é minha primeira escolha em novos projetos.

Próximos passos

Depois de ler este artigo, você pode:

1. Experimentar agora: abra seu projeto Astro e execute npx astro add node para testar SSR em cinco minutos
2. Avaliar suas necessidades: liste quais páginas do projeto precisam de renderização dinâmica e quais podem continuar estáticas
3. Aprofundar-se: conheça o recurso Server Islands, ou ilhas de servidor, lançado recentemente pelo Astro, que permite incorporar componentes SSR em páginas SSG com mais flexibilidade

Se você tiver problemas durante a configuração, faça uma pergunta na comunidade oficial do Astro no Discord. As respostas costumam ser rápidas e a comunidade é receptiva.

Por fim, evite otimização excessiva. Se seu site não recebe muito tráfego, com menos de 10 mil visualizações de página por dia, um site estático provavelmente é suficiente. Não há motivo para adicionar a complexidade do SSR. A escolha técnica deve atender ao negócio; não use uma tecnologia apenas por usar.

Boa configuração! Se tiver alguma dúvida, deixe um comentário.