O que é o Astro
O Astro é um framework web para sites orientados a conteúdo. Ele gera HTML no build ou no servidor e só envia JavaScript ao navegador nos componentes marcados para isso.
Ficha do framework
| Item | Valor |
|---|---|
| Tipo | Framework web para sites orientados a conteúdo |
| Exemplos citados pela documentação | Blogs, sites de marketing e lojas virtuais |
| Saída padrão | HTML renderizado no build ou no servidor |
| JavaScript no navegador | Só nos componentes com uma diretiva client:* |
| Node.js exigido | v22.23.4 ou superior. Versões ímpares, como a v23, não têm suporte |
| Versão de referência desta página | Astro 7.4 |
| Documentação oficial | docs.astro.build |
Princípios de design
A documentação descreve o Astro por cinco princípios.
| Princípio | O que a documentação afirma |
|---|---|
| Orientado a conteúdo | O Astro foi desenhado para mostrar o seu conteúdo |
| Servidor primeiro | Sites ficam mais rápidos quando o HTML é renderizado no servidor |
| Rápido por padrão | Deve ser impossível construir um site lento com o Astro |
| Fácil de usar | Você não precisa ser especialista para construir algo com o Astro |
| Focado no desenvolvedor | Você deve ter os recursos de que precisa para ter sucesso |
Arquitetura de ilhas
A página vira HTML estático. Cada componente interativo forma uma ilha, que carrega o próprio JavaScript separado do resto. A documentação descreve a ideia como pequenas regiões de JavaScript dentro de um mar de HTML. Como cada ilha roda isolada, um mesmo projeto aceita componentes de mais de um framework de interface.
| Tipo de ilha | Diretiva | Para que serve |
|---|---|---|
| Ilha cliente | client:* |
Componente que reage a cliques e outros eventos no navegador |
| Ilha de servidor | server:defer |
Conteúdo dinâmico renderizado sob demanda, fora da renderização do resto da página |
Diretivas de cliente
| Diretiva | Quando o JavaScript do componente carrega |
|---|---|
client:load |
De imediato, no carregamento da página |
client:idle |
Depois que a página termina a carga inicial |
client:visible |
Quando o componente entra na área visível da tela |
client:media |
Quando uma media query de CSS é atendida |
client:only |
De imediato, como o client:load, mas sem renderização no servidor |
Um componente sem diretiva vira HTML e não envia JavaScript nenhum. A diretiva entra na tag do componente, dentro do arquivo .astro:
---import Carrossel from '../components/Carrossel.jsx'---
<Carrossel client:visible />Ilha de servidor
A diretiva server:defer faz o componente renderizar sob demanda, separado do resto da página. O restante aparece sem esperar por ele. Ela serve a peças que mudam por visitante, como o avatar de um perfil conectado.
---import Avatar from '../components/Avatar.astro'---
<Avatar server:defer />Quando escolher o Astro
| Projeto | Indicação |
|---|---|
| Blog, documentação ou landing page com pouco JavaScript no navegador | Astro |
| Sistema com login, rotas dinâmicas e comportamento de produto | Next.js ou outra base de aplicação |
| Site publicado pelo painel visual, sem edição de arquivos | WordPress |
O site da Promovaweb migrou para o Astro para editar páginas e artigos com agentes. O conteúdo fica em Markdown e JSON dentro do repositório. O Codex e o Claude editam esses arquivos junto do código.
