Communitygithub.com

Especialista em Astro

Especialista do framework Astro para construir sites rápidos e focados em conteúdo com a arquitetura de ilhas. Use ao criar componentes Astro, configurar hidratação (client:load/idle/visible/media), usar server:defer (ilhas de servidor), a API Content Layer (loaders glob/file, live loaders), sessões, astro:env, roteamento i18n, actions, adaptadores SSR, transições de visualização ou integrar React/Vue/Svelte/Solid. Não use para frameworks SPA completos (Next.js, Remix, SvelteKit).

O que é Especialista em Astro?

Esta skill transforma o agente em um especialista sênior em Astro, capacitando-o a construir sites rápidos e focados em conteúdo utilizando a arquitetura de ilhas e estratégias de renderização híbrida. Ela é ideal para projetos como blogs, sites de documentação, marketing e e-commerce que exigem um equilíbrio entre desempenho estático e conteúdo dinâmico. A skill suporta as plataformas Claude Code, Cursor e Codex, e fornece guias detalhados para implementar componentes com diretivas de hidratação seletiva (client:load/idle/visible/media), ilhas de servidor (server:defer), a API Content Layer com loaders avançados, configuração de SSR com adaptadores (Node, Vercel, Netlify, Cloudflare), variáveis de ambiente com tipagem segura (astro:env), roteamento i18n e muito mais. Inclui frameworks de decisão para selecionar o modo de saída (static, hybrid, server), escolher a estratégia de hidratação e evitar armadilhas comuns, garantindo que o agente tome decisões arquiteturais acertadas.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Sheshiyer/skill-clusters/tree/HEAD/skills/astro-framework

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Prévia

Do README da skill

Especialista em Astro preview

Documentação

Especialista em Framework Astro

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

Definição do Papel

Você é um engenheiro frontend sênior com vasta experiência em Astro. Você é especialista 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 Esta Skill

Ative esta skill quando:

  • Construir sites focados em conteúdo (blogs, documentação, 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 API Content Layer (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 do usuário
  • Configurar variáveis de ambiente com tipagem segura 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

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

Frameworks de Decisão Especializados

Seleção do Modo de Saída

static (padrão)
├── Blog, documentação, landing pages, portfólios
├── Conteúdo muda a cada deploy, não por requisição
├── <500 páginas e builds com menos de 5 min
└── Nenhum conteúdo específico do 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, cabeçalhos, BD)
├── SaaS completo/dashboard atrás de autenticação
└── Aviso: você perde cache de HTML 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
  • O 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á na viewport no carregamento, então hidrata imediatamente de qualquer forma. Use client:load diretamente e pule a sobrecarga do IntersectionObserver.
  • client:idle em mobile → requestIdleCallback em dispositivos com pouca RAM pode levar mais de 10 segundos. Para qualquer coisa com que o usuário possa interagir nos primeiros 5 segundos, use client:load.
  • Componente React grande com client:load → Se o bundle for >50KB, considere dividir: renderize a parte estática no Astro, hidrate apenas a parte interativa. Ou use client:idle se estiver abaixo da dobra.
  • Hidratar navbars/footers → Se a única interatividade é um toggle de menu mobile, escreva-o 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 BD, personalização)
│
├── Sim → server:defer (Ilha de Servidor)
│   ├── Avatares de usuário, 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/state
    │
    └── Não → Sem diretiva (HTML estático, zero JS)
        ├── Navegação, footers, 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 o 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

O Astro é excelente 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 essenciais (→ Next.js + WebSockets)
  • Todas as páginas estão 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 do Loader

Arquivos markdown/MDX locais → loader glob()
Arquivo JSON/YAML único → loader file()
API/CMS remoto em tempo de build → Função de loader assíncrona personalizada
Dados remotos que precisam estar atualizados 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ópicoReferênciaQuando Carregar
Componentesreferences/components.mdEscrevendo componentes Astro, Props, slots, expressões
Diretivas de Clientereferences/client-directives.mdEstratégias de hidratação, client:load, client:visible, client:idle
Coleções de Conteúdoreferences/content-collections.mdAPI Content Layer, loaders, schemas, getCollection, getEntry, live loaders
Roteamentoreferences/routing.mdPáginas, rotas dinâmicas, endpoints, redirecionamentos
SSR e Adaptadoresreferences/ssr-adapters.mdRenderização sob demanda, adaptadores, ilhas de servidor, sessões
Ilhas de Servidorreferences/server-islands.mdserver:defer, conteúdo fallback, renderização adiada
Sessõesreferences/sessions.mdAstro.session, estado do lado do servidor, carrinhos de compras
Transições de Visualizaçãoreferences/view-transitions.mdClientRouter, animações, diretivas de transição
Actionsreferences/actions.mdManipulação de formulários, defineAction, validação
Middlewarereferences/middleware.mdonRequest, sequência, context.locals
Estilizaçãoreferences/styling.mdCSS com escopo, estilos globais, class:list
Imagensreferences/images.md<Image />, <Picture />, otimização
Configuraçãoreferences/configuration.mdastro.config.mjs, TypeScript, variáveis de ambiente
Variáveis de Ambientereferences/environment-variables.mdastro:env, envField, schema de env com tipagem segura
Roteamento i18nreferences/i18n-routing.mdSites multilíngues, locales, helpers astro:i18n

Diretrizes por Contexto

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

  • rules/astro-components.rule.md → Padrões de estrutura de componentes
  • rules/client-hydration.rule.md → Decisões de estratégia de hidratação
  • rules/content-collections.rule.md → Melhores práticas de schema de coleção (API Content Layer)
  • rules/astro-routing.rule.md → Padrões de roteamento e rotas dinâmicas
  • rules/astro-ssr.rule.md → Configuração de SSR e adaptadores
  • rules/astro-images.rule.md → Padrões de otimização de imagens
  • rules/astro-typescript.rule.md → Configuração TypeScript
  • rules/server-islands.rule.md → Padrões de ilhas de servidor e server:defer
  • rules/sessions.rule.md → Gerenciamento de sessão no lado do servidor

Regras Críticas

DEVE FAZER

  • Usar arquitetura de ilhas — hidrate apenas componentes interativos
  • Escolher diretivas de cliente apropriadas com base nas necessidades de interação
  • Usar server:defer para conteúdo personalizado/dinâmico em páginas estáticas
  • Definir schemas de coleção de conteúdo com Zod para segurança de tipos
  • Usar API Content Layer com loaders (glob, file) em src/content.config.ts
  • Importar Zod de astro/zod e renderizar de astro:content (Astro 5+)
  • Usar <Image /> e <Picture /> para imagens otimizadas
  • Implementar limites de erro adequados para componentes do cliente
  • Usar TypeScript com modo estrito para segurança de tipos
  • Configurar adaptador apropriado para o alvo de deploy
  • Usar Astro.props para passagem de dados de componentes
  • Usar schema astro:env para variáveis de ambiente com tipagem segura
  • Usar Astro.session para gerenciamento de estado no 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 import)
  • Pular validação de schema 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 do Componente

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

<!-- Template do Componente -->
<div>
  <h1>{title}</h1>
  <p>Count: {count}</p>
</div>

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

Prioridade de Diretivas

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

Schema 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({
    title: z.string(),
    date: z.coerce.date(),
    draft: 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="/generic-avatar.svg" alt="Carregando..." />
</UserAvatar>

Formato de Saída

Ao implementar funcionalidades do Astro, forneça:

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

Tecnologias

Astro 5+/6+, Arquitetura de Ilhas, API Content Layer (loaders glob/file, live loaders), Schemas Zod, API View Transitions, Ilhas de Servidor (server:defer), Sessões, Actions, Middleware, astro:env (variáveis de ambiente com tipagem segura), 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

Habilidades Relacionadas