Framework Web Astro

Visão Geral

Astro é um framework web projetado para sites ricos em conteúdo — blogs, documentações, portfólios, sites de marketing e e-commerce. Sua inovação principal é a Arquitetura de Ilhas: por padrão, o Astro envia zero JavaScript para o navegador. Componentes interativos são hidratados seletivamente como "ilhas" isoladas. O Astro suporta React, Vue, Svelte, Solid e outros frameworks de UI simultaneamente no mesmo projeto, permitindo que você escolha a ferramenta certa por componente.

Quando Usar Esta Habilidade

• Use ao construir um blog, site de documentação, página de marketing ou portfólio
• Use quando performance e Core Web Vitals são a prioridade máxima
• Use quando o projeto é rico em conteúdo com arquivos Markdown ou MDX
• Use quando você quer saída SSG (estática) com SSR opcional para rotas dinâmicas
• Use quando o usuário perguntar sobre arquivos .astro, Astro.props, coleções de conteúdo ou diretivas client:

Como Funciona

Passo 1: Configuração do Projeto

npm create astro@latest my-site
cd my-site
npm install
npm run dev

Adicione integrações conforme necessário:

npx astro add tailwind        # Tailwind CSS
npx astro add react           # React component support
npx astro add mdx             # MDX support
npx astro add sitemap         # Auto sitemap.xml
npx astro add vercel          # Vercel SSR adapter

Estrutura do projeto:

src/
  pages/          ← File-based routing (.astro, .md, .mdx)
  layouts/        ← Reusable page shells
  components/     ← UI components (.astro, .tsx, .vue, etc.)
  content/        ← Type-safe content collections (Markdown/MDX)
  styles/         ← Global CSS
public/           ← Static assets (copied as-is)
astro.config.mjs  ← Framework config

Passo 2: Sintaxe de Componentes Astro

Arquivos .astro têm uma cerca de código no topo (apenas para servidor) e um template abaixo:

---
// src/components/Card.astro
// This block runs on the server ONLY — never in the browser
interface Props {
  title: string;
  href: string;
  description: string;
}

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

<article class="card">
  <h2><a href={href}>{title}</a></h2>
  <p>{description}</p>
</article>

<style>
  /* Scoped to this component automatically */
  .card { border: 1px solid #eee; padding: 1rem; }
</style>

Passo 3: Páginas e Roteamento Baseados em Arquivos

src/pages/index.astro          → /
src/pages/about.astro          → /about
src/pages/blog/[slug].astro    → /blog/:slug (dynamic)
src/pages/blog/[...path].astro → /blog/* (catch-all)

Rota dinâmica com getStaticPaths:

---
// src/pages/blog/[slug].astro
export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;
const { Content } = await post.render();
---

<h1>{post.data.title}</h1>
<Content />

Passo 4: Coleções de Conteúdo

Coleções de conteúdo oferecem acesso type-safe a arquivos Markdown e MDX:

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

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    date: z.coerce.date(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };

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

const posts = (await getCollection('blog'))
  .filter(p => !p.data.draft)
  .sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf());
---

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

Passo 5: Ilhas — Hidratação Seletiva

Por padrão, componentes de frameworks de UI renderizam HTML estático sem JS. Use diretivas client: para hidratar:

---
import Counter from '../components/Counter.tsx';  // React component
import VideoPlayer from '../components/VideoPlayer.svelte';
---

<!-- Static HTML — no JavaScript sent to browser -->
<Counter initialCount={0} />

<!-- Hydrate immediately on page load -->
<Counter initialCount={0} client:load />

<!-- Hydrate when the component scrolls into view -->
<VideoPlayer src="/demo.mp4" client:visible />

<!-- Hydrate only when browser is idle -->
<Analytics client:idle />

<!-- Hydrate only on a specific media query -->
<MobileMenu client:media="(max-width: 768px)" />

…