Astro

O que é Astro?

Astro é um framework web focado em conteúdo construído com base em uma aposta simples: a maioria das páginas não precisa de muito JavaScript. Ele renderiza páginas para HTML por padrão, não envia JavaScript para o cliente a menos que você solicite e permite adicionar componentes interativos apenas onde eles são realmente necessários.

Esse design torna o Astro excepcionalmente bom para os tipos de sites que compõem grande parte da web: blogs, documentações, páginas de marketing, portfólios e produtos com foco em conteúdo. Ele não é contra o JavaScript — ele é a favor da moderação. Você obtém a interatividade de que precisa e nada além disso.

componentes .astro

Um componente Astro é um arquivo com um script de frontmatter, um template e estilos escopados opcionais.

---
// src/components/Card.astro
interface Props {
  title: string;
  href: string;
}

const { title, href } = Astro.props;
---

<a class="card" href={href}>
  <h3>{title}</h3>
  <slot />
</a>

<style>
  .card {
    display: block;
    border-radius: 1rem;
    padding: 1.5rem;
  }
</style>

O frontmatter é executado no servidor no momento do build ou por requisição. O template é HTML com expressões semelhantes a JSX, e o <slot /> permite que um componente pai passe filhos. Por padrão, os estilos são escopados ao componente. Como o componente é executado no servidor, você pode consultar bancos de dados, ler arquivos e chamar APIs diretamente no frontmatter.

Roteamento baseado em arquivos

Arquivos em src/pages tornam-se rotas, e segmentos dinâmicos utilizam colchetes.

src/pages/
├── index.astro            # /
├── about.astro            # /about
├── blog/
│   ├── index.astro        # /blog
│   └── [slug].astro       # /blog/:slug
└── rss.xml.js             # /rss.xml

Para rotas dinâmicas, você exporta getStaticPaths para declarar quais páginas devem ser geradas, ou utiliza SSR para renderizar sob demanda.

Content collections

Content collections são a resposta do Astro para conteúdo estruturado. Você define um schema e cada entrada em markdown ou JSON é validada no momento do build.

// src/content.config.ts
import { defineCollection, z } from "astro:content";

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    publishedAt: z.coerce.date(),
    tags: z.array(z.string()).default([]),
  }),
});

export const collections = { blog };

---
// src/pages/blog/index.astro
import { getCollection } from "astro:content";

const posts = (await getCollection("blog"))
  .sort((a, b) => b.data.publishedAt.valueOf() - a.data.publishedAt.valueOf());
---

<ul>
  {posts.map((post) => (
    <li>
      <a href={`/blog/${post.id}`}>{post.data.title}</a>
    </li>
  ))}
</ul>

Você ganha type safety, validação e uma maneira limpa de consultar conteúdo sem a necessidade de um banco de dados. Para um site com centenas de posts ou páginas de documentação, isso representa uma melhoria significativa na qualidade de vida do desenvolvimento.

A arquitetura de ilhas

Este é o recurso definidor do Astro. Uma página é HTML estático, e qualquer componente interativo são ilhas que hidratam de forma independente. Você controla quando cada ilha é carregada através de uma diretiva de cliente.

---
import Counter from "../components/Counter.jsx";
import Comments from "../components/Comments.jsx";
---

<Counter client:load />
<Comments client:visible />

As diretivas são:

• client:load hidrata imediatamente — para interatividades críticas acima da dobra (above-the-fold).
• client:idle hidrata assim que o navegador estiver livre.
• client:visible hidrata quando o componente entra na área de visualização (scroll).
• client:only pula a renderização no servidor e renderiza apenas no navegador.
• client:media hidrata quando uma media query for correspondida.

Escolher a diretiva menos “ansiosa” que ainda funcione mantém a página rápida. A maioria das páginas de conteúdo não precisa de nenhuma.

Traga sua própria biblioteca de UI

O Astro consegue renderizar componentes de React, Vue, Svelte, Solid e Preact — no mesmo projeto.

---
import ReactChart from "../components/Chart.jsx";
import VueForm from "../components/Form.vue";
---

<ReactChart client:load data={data} />
<VueForm client:visible />

Cada framework é uma integração opcional. Você pode usar React para uma island e Svelte para outra, ou dispensar frameworks completamente. Essa flexibilidade significa que você nunca fica preso a uma tecnologia e pode adotar uma biblioteca apenas onde ela for realmente necessária.

SSR e adapters

O Astro é estático por padrão, mas pode renderizar sob demanda. Adicione um adapter para a sua plataforma e configure as rotas para renderização no servidor.

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

export default defineConfig({
  output: "server",
  adapter: node({ mode: "standalone" }),
});

Endpoints de API ficam em src/pages/api e exportam métodos HTTP, e server islands permitem que você renderize fragmentos dinâmicos dentro de páginas que, de outra forma, seriam estáticas. Isso torna o Astro ideal para sites híbridos: um blog estático com um dashboard dinâmico, ou um site de marketing com seções personalizadas.

Melhores práticas

• Priorize componentes .astro; adicione componentes de framework apenas para interatividade.
• Use a diretiva de cliente menos “eager” que funcione.
• Mantenha o conteúdo em coleções com um schema em vez de markdown de formato livre.
• Isole os estilos com blocos <style> de componentes ou com a ferramenta de CSS de sua escolha.
• Renderize páginas estáticas no momento do build e reserve o SSR para rotas dinâmicas.
• Use layouts para shells compartilhados e metadados.
• Otimize imagens com os componentes de imagem integrados.

Erros comuns

• Adicionar client:load em todo lugar e perder o benefício do zero-JavaScript.
• Recorrer a um framework de UI quando um componente .astro seria suficiente.
• Esquecer de definir um schema e perder a tipagem (type safety) nas coleções.
• Presumir que o Astro não consegue criar apps dinâmicos e ignorar o SSR.
• Misturar frameworks de UI demais e inflar o projeto sem necessidade.
• Usar client-side fetching para conteúdos que poderiam ser renderizados no build time.

Próximos passos

O Astro é a escolha pragmática para sites com foco em conteúdo que ainda precisam de pontos de interatividade. Reforce seus conhecimentos de HTML e CSS e, em seguida, compare esse modelo com Next.js, Nuxt e SvelteKit. Depois, crie um pequeno blog com uma content collection e uma island interativa para analisar as vantagens e desvantagens por conta própria.