Pular para o conteúdo

Adaptadores de Renderização sob Demanda

O Astro permite que você escolha renderização sob demanda para algumas ou todas as suas páginas e endpoints. Isso também é conhecido como renderização no lado do servidor (SSR): gerar páginas HTML no servidor quando solicitadas e enviá-las ao cliente. Um adaptador é usado para executar seu projeto no servidor e processar essas solicitações.

Essa renderização sob demanda lhe permite:

  • Implementar sessões para um estado de login na sua aplicação.
  • Renderizar dados de uma API chamada dinamicamente com fetch().
  • Fazer deploy do seu site em uma hospedagem utilizando um adaptador.

Considere ativar a renderização no servidor sob demanda em seu projeto Astro se precisar do seguinte:

  • Endpoints de API: Criar páginas específicas que funcionam como endpoints de API para tarefas como acesso a banco de dados, autenticação e autorização enquanto mantém dados sensíveis ocultos do cliente.

  • Páginas protegidas: Restringir o acesso a uma página com base nos privilégios do usuário, gerenciando o acesso do usuário no servidor.

  • Conteúdo que atualiza frequentemente: Gerar páginas individuais sem exigir um novo build estático do seu site. Isso é útil quando o conteúdo de uma página é atualizado com frequência.

O Astro mantém adaptadores oficiais para Node.js, Vercel, Netlify e Cloudflare.

Encontre ainda mais adaptadores mantidos pela comunidade (por exemplo, Deno, SST e AWS) em nosso diretório de integrações.

Adaptadores de SSR

Habilitando a renderização no servidor sob demanda

Seção intitulada Habilitando a renderização no servidor sob demanda

Os dois modos de saída de renderização sob demanda do Astro (server e hybrid) permitem que você aproveite a performance do site estático ao pré-renderizar rotas individuais sempre que possível, quer você tenha uma aplicação totalmente dinâmica ou um site majoritariamente estático que precise de renderização sob demanda apenas para rotas selecionadas.

Para decidir qual deles usar em seu projeto, escolha a opção de output que representa como a maioria de suas páginas e rotas será renderizada:

  • output: 'server': Renderizado sob demanda por padrão. Use essa opção quando a maior parte ou todo o seu site ou aplicativo precisar ser renderizado pelo servidor quando solicitado. Qualquer página individual ou endpoint pode ativar a pré-renderização.
  • output: 'hybrid': Pré-renderizado para HTML por padrão. Use essa opção quando a maior parte do seu site deve ser estática. Qualquer página individual ou endpoint pode desativar a pré-renderização.

Como o servidor precisará gerar pelo menos algumas páginas sob demanda, esses dois modos exigem que você adicione um adaptador para executar as funções do servidor.

Para fazer o deploy de um projeto no modo server ou hybrid, você precisa adicionar um adaptador. Isso ocorre porque esses dois modos exigem um runtime de servidor: o ambiente que executa o código no servidor para gerar páginas quando elas são solicitadas. Cada adaptador permite que o Astro produza um script que executa seu projeto em um runtime específico, como Vercel, Netlify ou Cloudflare.

Você pode encontrar os adaptadores oficiais e da comunidade em nosso diretório de integrações. Escolha o que corresponde ao seu ambiente de deploy.

Você pode adicionar qualquer um dos adaptadores oficiais mantidos pelo Astro com o comando astro add. Ele irá instalar o adaptador e fazer as mudanças apropriadas em seu arquivo astro.config.mjs em uma só etapa.

Por exemplo, para instalar o adaptador para Vercel, execute:

Terminal window
npx astro add vercel

Você também pode adicionar um adaptador manualmente, instalando o pacote e atualizando o arquivo astro.config.mjs por conta própria.

Por exemplo, para instalar o adaptador para Vercel manualmente:

  1. Instale o adaptador nas dependências do seu projetado utilizando seu gerenciador de pacotes preferido:

    Terminal window
    npm install @astrojs/vercel
  2. Adicione o adaptador no import e default export do seu arquivo astro.config.mjs, juntamente com o modo de output desejado:

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import vercel from '@astrojs/vercel/serverless';
    export default defineConfig({
    output: 'server',
    adapter: vercel(),
    });

    Observe que adaptadores diferentes também podem ter definições de configuração diferentes. Leia a documentação de cada adaptador e aplique as opções de configuração necessárias ao adaptador escolhido no arquivo astro.config.mjs.

Para ativar a renderização sob demanda, você deve atualizar sua configuração de output para um dos dois modos de renderização no servidor.

Por exemplo, para configurar uma aplicação altamente dinâmica em que cada página é renderizada sob demanda por padrão, adicione output: 'server' à sua configuração do Astro:

astro.config.mjs
import { defineConfig } from 'astro/config';
import node from "@astrojs/node";
export default defineConfig({
output: 'server',
adapter: node({
mode: "standalone"
})
});

Ativando a pré-renderização no modo server

Seção intitulada Ativando a pré-renderização no modo server

Para uma aplicação renderizada principalmente no servidor configurada como output: server, adicione export const prerender = true a qualquer página ou rota para pré-renderizar uma página estática ou um endpoint:

src/pages/minhapagina.astro
---
export const prerender = true;
// ...
---
<html>
<!-- Página estática e pré-renderizada aqui... -->
</html>
src/pages/minhapagina.mdx
---
layout: '../layouts/markdown.astro'
title: 'Minha página'
---
export const prerender = true;
# Esta é minha página estática e pré-renderizada
src/pages/meuendpoint.js
export const prerender = true;
export async function GET() {
return new Response(
JSON.stringify({
message: `Este é meu endpoint estático`,
}),
);
}

Desativando a pré-renderização no modo hybrid

Seção intitulada Desativando a pré-renderização no modo hybrid

Para um site predominantemente estático configurado como output: hybrid, adicione export const prerender = false a todos os arquivos que devem ser renderizados pelo servidor sob demanda:

src/pages/numeroaleatorio.js
export const prerender = false;
export async function GET() {
let number = Math.random();
return new Response(
JSON.stringify({
number,
message: `Here's a random number: ${number}`,
}),
);
}

Recursos de renderização sob demanda

Seção intitulada Recursos de renderização sob demanda

Com o streaming de HTML, um documento é dividido em partes, enviado pela rede em ordem e renderizado na página nessa ordem. No modo server ou hybrid, o Astro usa o streaming de HTML para enviar cada componente ao navegador à medida que ele os renderiza. Isso garante que o usuário veja o HTML o mais rápido possível, embora as condições da rede possam fazer com que documentos grandes sejam baixados lentamente e a espera pela obtenção de dados possa bloquear a renderização da página.

Nos modos server e hybrid, uma página ou endpoint de API pode verificar, definir, obter e excluir cookies.

O exemplo abaixo atualiza o valor de um cookie para um contador de visualizações de página:

src/pages/index.astro
---
let contagem = 0
if (Astro.cookies.has("contagem")) {
const cookie = Astro.cookies.get("contagem")
contagem = cookie.number() + 1
}
Astro.cookies.set("contagem", contagem)
---
<html>
<h1>Contagem = {contagem}</h1>
</html>

Veja mais detalhes sobre Astro.cookies e o tipo AstroCookie na referência da API.

Você também consegue retornar uma Response de qualquer página usando a renderização sob demanda.

O exemplo abaixo retorna um erro 404 em uma página dinâmica depois de procurar um ID no banco de dados:

src/pages/[id].astro
---
import { getProduto } from '../api';
const produto = await getProduto(Astro.params.id);
// O produto não foi encontrado
if (!produto) {
return new Response(null, {
status: 404,
statusText: 'Não encontrado'
});
}
---
<html>
<!-- Página aqui... -->
</html>

O Astro.request é um objeto Request padrão. Ele pode ser usado para obter a url, headers, method e até mesmo o corpo da requisição.

Nos modos server e hybrid, você pode acessar informações adicionais desse objeto para páginas que não são geradas estaticamente.

Os cabeçalhos da requisição estão disponíveis em Astro.request.headers. Isso funciona como o Request.headers do navegador. É um objeto Headers no qual você pode recuperar cabeçalhos, como o cookie.

src/pages/index.astro
---
const cookie = Astro.request.headers.get('cookie');
// ...
---
<html>
<!-- Página aqui... -->
</html>

O método HTTP usado na requisição está disponível como Astro.request.method. Isso funciona como o Request.method do navegador. Ele retorna a representação em string do método HTTP usado na requisição.

src/pages/index.astro
---
console.log(Astro.request.method) // GET (quando acessada no navegador)
---

Veja mais detalhes sobre o Astro.request na referência da API.

Um endpoint de servidor, também conhecido como Rota de API, é uma função especial exportada de um arquivo .js ou .ts dentro da pasta src/pages/. Um recurso poderoso de renderização sob demanda no lado do servidor, as rotas de API são capazes de executar código com segurança no servidor.

A função recebe um contexto de endpoint e retorna uma Response.

Para mais informações, consulte nosso Guia de Endpoints.