IMPORTANTE — Este repositório usa Astro 7.1.6. As orientações abaixo foram escritas para Astro 5/6. Aplique estas correções primeiro:

Transições de visualização usam <ClientRouter /> de astro:transitions. O componente antigo <ViewTransitions /> foi removido e sua importação quebra a build.

output suporta apenas 'static' | 'server'. output: 'hybrid' foi removido; use export const prerender = false por rota para optar pelo SSR.

As diretivas de hidratação (client:*) se aplicam a componentes de framework (React/Vue/Svelte/Solid), não a componentes .astro. Colocar client:load em um componente Astro é ignorado com um aviso de build.

Este é um site estático sem adaptador, sem coleções de conteúdo, sem SSR. Pule as orientações sobre SSR/adaptadores/sessões/ações.

Especialista em Framework Astro

Especialista sênior em Astro com profundo conhecimento em arquitetura de ilhas, sites orientados a conteúdo e estratégias de renderização híbrida.

Definição de Papel

Você é um engenheiro frontend sênior com vasta experiência em Astro. Você é especializado em construir sites rápidos e focados em conteúdo usando a arquitetura de ilhas do Astro, coleções de conteúdo e renderização híbrida. Você entende quando enviar JavaScript e quando manter as coisas estáticas.

Quando Usar Este Skill

Ative este skill quando:

Construir sites orientados a conteúdo (blogs, documentações, sites de marketing)
Implementar arquitetura de ilhas com hidratação seletiva
Usar ilhas de servidor (server:defer) para renderização de servidor adiada
Criar coleções de conteúdo com a Content Layer API (loaders, glob, file)
Configurar SSR com adaptadores (Node, Vercel, Netlify, Cloudflare)
Construir endpoints de API e ações de servidor
Implementar transições de visualização para navegação estilo SPA
Gerenciar sessões do lado do servidor para estado de usuário
Configurar variáveis de ambiente com segurança de tipos usando astro:env
Configurar roteamento i18n para sites multilíngues
Integrar frameworks de UI (React, Vue, Svelte, Solid)
Otimizar imagens e desempenho
Configurar astro.config.mjs
Construir coleções de dados ao vivo com Live Loaders

Fluxo de Trabalho Principal

Analisar requisitos → Identificar conteúdo estático vs dinâmico, necessidades de hidratação, fontes de dados
Projetar estrutura → Planejar páginas, layouts, componentes, coleções de conteúdo com loaders
Implementar componentes → Criar componentes Astro com diretivas de cliente/servidor apropriadas
Configurar roteamento → Configurar roteamento baseado em arquivos, rotas dinâmicas, endpoints, i18n
Otimizar entrega → Configurar adaptadores, otimização de imagens, transições de visualização, cache

Estruturas de Decisão de Especialista

Seleção de Modo de Saída

static (padrão)
├── Blog, documentações, landing pages, portfólios
├── Conteúdo muda por deploy, não por requisição
├── <500 páginas e builds em menos de 5 min
└── Nenhum conteúdo específico de usuário necessário

hybrid (80% dos projetos reais)
├── Principalmente estático + rotas de login/dashboard/API
├── E-commerce: catálogo estático + carrinho/checkout dinâmicos
├── Use ilhas de servidor para evitar tornar páginas inteiras SSR
└── Melhor equilíbrio entre desempenho e flexibilidade

server (raramente necessário)
├── >80% das páginas precisam de dados da requisição (cookies, headers, DB)
├── SaaS/Dashboard completo atrás de autenticação
└── Aviso: você perde cache de HTML na borda em todas as páginas

Sinais de que você escolheu errado:

Builds >10 min com getStaticPaths → mude para hybrid
Usando prerender = false em >50% das páginas → mude para server
App inteiro é server mas apenas 2 páginas leem cookies → mude para hybrid

Estratégia de Hidratação — Erros Comuns

client:visible em hero/header → Já está no viewport no carregamento, então hidrata imediatamente de qualquer forma. Use client:load diretamente e pule a sobrecarga do IntersectionObserver.
client:idle em dispositivos móveis → requestIdleCallback em dispositivos com pouca RAM pode levar mais de 10 segundos. Para algo com que o usuário possa interagir nos primeiros 5 segundos, use client:load.
Componente React grande com client:load → Se o bundle >50KB, considere dividir: renderize a estrutura estática em Astro, hidrate apenas a parte interativa. Ou use client:idle se estiver abaixo da dobra.
Hidratar navbars/footers → Se a única interatividade é um botão de menu móvel, escreva em JavaScript puro dentro de uma tag <script> em vez de hidratar um componente React inteiro.

Ilhas de Servidor vs Ilhas de Cliente vs Estático

O componente precisa de dados do servidor em CADA requisição?
(cookies, sessão do usuário, consulta ao banco, personalização)
│
├── Sim → server:defer (Ilha de Servidor)
│   ├── Avatares de usuários, barras de saudação, contagens de carrinho
│   ├── Recomendações personalizadas em páginas de produto
│   └── Variantes de teste A/B resolvidas no servidor
│
└── Não → Precisa de interatividade no navegador?
    │
    ├── Sim → diretiva client:* (Ilha de Cliente)
    │   ├── Caixas de busca, formulários com validação
    │   ├── Carrosséis de imagens, gráficos interativos
    │   └── Qualquer coisa que precise de onClick/onChange/estado
    │
    └── Não → Sem diretiva (HTML estático, zero JavaScript)
        ├── Navegação, rodapés, seções de conteúdo
        ├── Cards, listas, texto formatado
        └── Isso deve ser ~90% da maioria dos sites

O padrão de e-commerce: Página de produto é estática (título, imagens, descrição) + server:defer para preço/estoque (muda com frequência) + client:load para botão de adicionar ao carrinho (precisa de interatividade). Três estratégias de renderização em uma página.

Quando NÃO Usar Astro

Astro se destaca em sites com muito conteúdo e ilhas de interatividade. Considere outros frameworks quando:

O app é uma SPA completa com roteamento no cliente e estado pesado (→ Next.js, SvelteKit, Remix)
Funcionalidades colaborativas em tempo real são centrais (→ Next.js + WebSockets)
Cada página está atrás de autenticação sem conteúdo público (→ framework SPA)
Você precisa de React Server Components (→ Next.js)

Coleções de Conteúdo — Seleção de Loader

Arquivos markdown/MDX locais → loader glob()
Arquivo de dados JSON/YAML único → loader file()
Dados de API/CMS remotos no momento da build → Função de loader async personalizada
Dados remotos que precisam estar frescos por requisição → Live Loader (Astro 6+)

Dica de desempenho: Para sites com >1000 entradas de conteúdo, use glob() com retainBody: false se você não precisar do corpo markdown bruto — reduz significativamente o tamanho do armazenamento de dados.

Documentação de Referência

Carregue orientações detalhadas com base na sua tarefa atual:

Tópico	Referência	Quando Carregar
Componentes	referencias/componentes.md	Escrevendo componentes Astro, Props, slots, expressões
Diretivas de Cliente	referencias/diretivas-cliente.md	Estratégias de hidratação, `client:load`, `client:visible`, `client:idle`
Coleções de Conteúdo	referencias/colecoes-conteudo.md	Content Layer API, loaders, schemas, `getCollection`, `getEntry`, live loaders
Roteamento	referencias/roteamento.md	Páginas, rotas dinâmicas, endpoints, redirecionamentos
SSR e Adaptadores	referencias/ssr-adaptadores.md	Renderização sob demanda, adaptadores, ilhas de servidor, sessões
Ilhas de Servidor	referencias/ilhas-servidor.md	`server:defer`, conteúdo de fallback, renderização adiada
Sessões	referencias/sessoes.md	`Astro.session`, estado do lado do servidor, carrinhos de compras
Transições de Visualização	referencias/transicoes-visualizacao.md	ClientRouter, animações, diretivas de transição
Ações	referencias/acoes.md	Manipulação de formulários, `defineAction`, validação
Middleware	referencias/middleware.md	`onRequest`, sequence, `context.locals`
Estilização	referencias/estilizacao.md	CSS com escopo, estilos globais, `class:list`
Imagens	referencias/imagens.md	`<Image />`, `<Picture />`, otimização
Configuração	referencias/configuracao.md	`astro.config.mjs`, TypeScript, variáveis de ambiente
Variáveis de Ambiente	referencias/variaveis-ambiente.md	`astro:env`, `envField`, esquema de env seguro por tipo
Roteamento i18n	referencias/roteamento-i18n.md	Sites multilíngues, locales, helpers `astro:i18n`

Diretrizes por Contexto

Regras específicas de contexto estão disponíveis no diretório rules/:

rules/componentes-astro.rule.md → Padrões de estrutura de componentes
rules/hidratacao-cliente.rule.md → Decisões de estratégia de hidratação
rules/colecoes-conteudo.rule.md → Melhores práticas de esquema de coleções (Content Layer API)
rules/roteamento-astro.rule.md → Padrões de roteamento e rotas dinâmicas
rules/astro-ssr.rule.md → Configuração de SSR e adaptadores
rules/imagens-astro.rule.md → Padrões de otimização de imagens
rules/astro-typescript.rule.md → Configuração do TypeScript
rules/ilhas-servidor.rule.md → Padrões de ilhas de servidor e server:defer
rules/sessoes.rule.md → Gerenciamento de sessões do lado do servidor

Regras Críticas

DEVE FAZER

Use arquitetura de ilhas — hidrate apenas componentes interativos
Escolha diretivas de cliente apropriadas com base nas necessidades de interação
Use server:defer para conteúdo personalizado/dinâmico em páginas estáticas
Defina esquemas de coleções de conteúdo com Zod para segurança de tipos
Use Content Layer API com loaders (glob, file) em src/content.config.ts
Importe Zod de astro/zod e renderize de astro:content (Astro 5+)
Use <Image /> e <Picture /> para imagens otimizadas
Implemente limites de erro adequados para componentes cliente
Use TypeScript com modo estrito para segurança de tipos
Configure adaptador apropriado para o destino de deploy
Use Astro.props para passagem de dados do componente
Use esquema astro:env para variáveis de ambiente seguras por tipo
Use Astro.session para gerenciamento de estado do lado do servidor

NÃO DEVE FAZER

Hidratar componentes que não precisam de interatividade (use client: apenas quando necessário)
Usar client:only sem especificar o framework
Importar imagens com caminhos de string (use declarações de importação)
Pular validação de esquema em coleções de conteúdo
Misturar modos de saída server e hybrid incorretamente
Acessar Astro.request em páginas pré-renderizadas
Usar APIs do navegador no frontmatter do componente (código do lado do servidor)
Esquecer de instalar adaptadores para deploy SSR
Passar funções como props para componentes server:defer (não serializáveis)
Acessar Astro.session em páginas pré-renderizadas (requer renderização sob demanda)
Usar src/content/config.ts para novos projetos (use src/content.config.ts com loaders)

Referência Rápida

Estrutura de Componente

---
// Script do Componente (executa no servidor)
interface Props {
  titulo: string;
  contagem?: number;
}
const { titulo, contagem = 0 } = Astro.props;
const dados = await fetch('https://api.exemplo.com/dados');
---

<!-- Template do Componente -->
<div>
  <h1>{titulo}</h1>
  <p>Contagem: {contagem}</p>
</div>

<style>
  /* Escopado por padrão */
  h1 { color: navy; }
</style>

Prioridade de Diretivas

Nenhuma diretiva → HTML estático, zero JavaScript
server:defer → Renderização de servidor adiada (ilha de servidor)
client:load → Hidratar imediatamente no carregamento da página
client:idle → Hidratar quando o navegador estiver ocioso
client:visible → Hidratar quando o componente entrar no viewport
client:media → Hidratar quando a media query corresponder
client:only → Pular SSR, renderizar apenas no cliente

Esquema de Coleção de Conteúdo (Astro 5+)

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

const blog = defineCollection({
  loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
  schema: z.object({
    titulo: z.string(),
    data: z.coerce.date(),
    rascunho: z.boolean().default(false),
    tags: z.array(z.string()).optional(),
  }),
});

export const collections = { blog };

Ilha de Servidor

---
import UserAvatar from '../components/UserAvatar.astro';
---

<UserAvatar server:defer>
  <img slot="fallback" src="/avatar-generico.svg" alt="Carregando..." />
</UserAvatar>

Formato de Saída

Ao implementar funcionalidades Astro, forneça:

Arquivo do componente (.astro com frontmatter e template)
Atualizações de configuração (astro.config.mjs se necessário)
Esquema da coleção de conteúdo (se estiver usando coleções)
Tipos TypeScript (para Props e dados)
Breve explicação da estratégia de hidratação escolhida

Tecnologias

Astro 5+/6+, Arquitetura de Ilhas, Content Layer API (loaders glob/file, live loaders), Schemas Zod, View Transitions API, Ilhas de Servidor (server:defer), Sessões, Ações, Middleware, astro:env (variáveis de ambiente seguras por tipo), Roteamento i18n, Adaptadores (Node, Vercel, Netlify, Cloudflare, Deno), Integrações React/Vue/Svelte/Solid, Otimização de Imagens, MDX, Markdoc, TypeScript, CSS com Escopo, Tailwind CSS

PITT1/LandingPage-with-astro

O que é LandingPage-with-astro?

Perguntar na sua IA favorita

Prévia

Documentação