farulwananda/skills

FW Escrevendo Astro

Escopo e primeiras decisões

Use este skill para componentes, roteamento, conteúdo, renderização e integrações específicas do Astro. Não o use para prescrever aspectos internos do React, uma arquitetura de backend ou um provedor de deploy; combine o skill da estrutura/tempo de execução relevante apenas quando necessário.

Antes de editar, inspecione o package.json, o arquivo de lock, as versões do Astro e do adaptador, astro.config.*, tsconfig, rotas/layouts/configuração de conteúdo existentes e scripts do repositório. Siga a documentação da versão instalada e as convenções existentes. Não instale integrações, atualize dependências, faça deploy ou chame serviços pagos sem autorização.

• Prefira HTML pré-renderizado para conteúdo que pode ser construído antecipadamente. O frontmatter é executado em tempo de construção para rotas pré-renderizadas e no servidor para rotas sob demanda; não é código do navegador.
• Use SSR para requisitos reais de tempo de requisição, como conteúdo autenticado ou dados frescos. Requer um adaptador compatível. Em versões que suportam o modelo atual, a saída estática padrão pode optar por rotas individuais para SSR com export const prerender = false; output: 'server' torna SSR o padrão e permite exceções prerender = true. Versões mais antigas têm configuração híbrida diferente: inspecione antes de migrar.
• Um site totalmente estático normalmente não precisa de adaptador. Não iguale Astro com Cloudflare ou imponha SSR em conteúdo estático.
• Preserve acessibilidade, escape e limites de confiança. Não interpole HTML não confiável com set:html; sanitize a renderização de formato confiável em seu limite de entrada real.

Componentes nativos e props válidas

Use componentes .astro para layout e conteúdo estático. Declare Props quando um componente aceita props; páginas sem props não precisam de interface cerimonial. Use os atributos reais do elemento, encaminhe atributos deliberadamente e evite um tag polimórfica com conjuntos de atributos incompatíveis. Um card linkado pode usar um link dentro de um article em vez de enviar href para um article. Não aninhe controles interativos dentro de um âncora de envoltório.

ASTRO-CARD — src/components/Card.astro completo; nenhuma biblioteca CSS necessária:

---
import type { HTMLAttributes } from 'astro/types';

interface Props extends Omit<HTMLAttributes<'article'>, 'title'> {
  title: string;
  description?: string;
  href?: string;
}

const { title, description, href, class: className, ...rest } = Astro.props;
---

<article {...rest} class:list={['card', className]}>
  <h2>{href ? <a href={href}>{title}</a> : title}</h2>
  {description && <p>{description}</p>}
  <slot />
</article>

Use slots nomeados para regiões de conteúdo explícitas e class:list para classes condicionais. Valide destinos de link não confiáveis separadamente; um tipo string não é validação de URL.

Comportamento pequeno do navegador antes de islands de framework

Use HTML semântico primeiro (details, formulários nativos), depois um <script> processado pequeno quando o comportamento do navegador for necessário. Não adicione React/Vue/Svelte apenas para alternar um menu. Scripts do Astro são agrupados/deduplicados; selecione todas as instâncias do componente ou use um elemento personalizado com escopo. Com navegação do lado do cliente, siga o ciclo de vida do roteador instalado e evite listeners duplicados. Valores de frontmatter não estão automaticamente disponíveis em scripts do navegador; passe apenas dados não secretos através de atributos DOM ou props explícitos.

ASTRO-BUTTON — src/components/Counter.astro completo, para navegação comum de página inteira:

<button type="button" data-counter aria-label="Incrementar contagem">0</button>
<script>
  document.querySelectorAll<HTMLButtonElement>('button[data-counter]').forEach((button) => {
    let count = 0;
    button.addEventListener('click', () => {
      button.textContent = String(++count);
    });
  });
</script>

Use uma island de framework quando os componentes existentes do framework ou estado interativo substancial a justificarem, com uma integração já instalada. Escolha client:load para comportamento imediatamente necessário, client:idle para comportamento não crítico, client:visible para conteúdo fora da tela e client:media para uma necessidade real dependente de mídia. Componentes sem uma diretiva client:* renderizam HTML sem hidratação do framework. client:only pula a renderização do servidor e precisa de uma experiência de carregamento/fallback intencional, não um trabalho paliativo genérico.

Coleções de Conteúdo seguem a versão instalada

Use coleções para conteúdo estruturado repetido, não para toda página isolada. Inspecione a configuração existente e os identificadores de entrada antes de editar:

• Astro 5 introduziu o modelo de loader da Camada de Conteúdo, normalmente em src/content.config.ts. Projetos legados podem usar src/content/config.ts e type: 'content' em vez de loaders. Estes não são locais de arquivo/APIs intercambiáveis.
• Verifique a exportação Zod instalada. O exemplo a seguir visa a exportação z do Astro 5 de astro:content; a documentação atual usa astro/zod. Não substitua imports mecanicamente em uma versão que não possui esse módulo.
• Entradas de loader usam id; não assuma APIs legadas de slug ou entry.render(). Para renderização da Camada de Conteúdo, use o helper render(entry) suportado. MDX requer sua integração se arquivos MDX estiverem incluídos.

ASTRO-COLLECTION-V5 — src/content.config.ts completo para Astro 5 com entradas Markdown locais:

import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };

ASTRO-COLLECTION-LIST — página completa src/pages/blog/index.astro, emparelhada com essa coleção e pelo menos uma entrada Markdown com esquema válido:

---
import { getCollection } from 'astro:content';
const posts = await getCollection('blog', ({ data }) => !import.meta.env.PROD || !data.draft);
posts.sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
---
<h1>Blog</h1>
<ul>{posts.map((post) => <li>{post.data.title}</li>)}</ul>

Esta lista deliberadamente não inventa URLs de página de detalhes. Se adicionar links, implemente rotas dinâmicas correspondentes e getStaticPaths() para páginas pré-renderizadas. Verifique rascunhos nas rotas de detalhes, bem como nas listagens; filtrar apenas o índice não é controle de acesso. Conteúdo privado em tempo de requisição não deve vazar através da saída de build ou caches públicos.

Consistência de localidade, canônico e 404

Escolha a política de URL antes de alterar rotas: site de produção configurado, base de deploy, formato de barra final/build, prefixos de localidade, comportamento da raiz e comportamento de fallback devem concordar com os arquivos reais e redirecionamentos do host.

• Use rotas baseadas em pastas. Com prefixDefaultLocale: false, páginas no idioma padrão ficam na raiz; outras localidades têm pastas. Com true, todos os idiomas têm pastas de localidade e o índice raiz ainda precisa de tratamento intencional.
• Use helpers astro:i18n suportados pela versão quando útil. A configuração não traduz conteúdo nem cria páginas ausentes. Link apenas traduções existentes; preserve um caminho equivalente significativo ao alternar idiomas.
• URLs canônicas devem usar a origem de produção e o caminho canônico escolhido, não host/query parameters arbitrários de Astro.url.href. Defina site para o deploy; considere base e normalização de barra final. Defina lang do documento e emita alternativas hreflang apenas para equivalentes reais com links recíprocos. Não canonalize todas as localidades para inglês.
• Implemente src/pages/404.astro quando uma página de erro personalizada for necessária. Em caminhos SSR, retorne um status 404 real, não um corpo de erro bem-sucedido. Em hospedagem estática, verifique se o arquivo 404 gerado é servido com status 404. Não use fallback SPA para um site de várias páginas nem redirecione todo caminho de localidade ausente para a página inicial. Evite indexar páginas de erro e não dê a cada URL ausente um auto-canônico.

ASTRO-CANONICAL-FRAGMENT — exemplo parcial de layout, não uma página standalone. Assume que site está configurado e o pathname atual já obedece à política de base/localidade/barra do repositório:

---
if (!Astro.site) throw new Error('Configure a URL do site de produção');
const canonical = new URL(Astro.url.pathname, Astro.site);
---
<link rel="canonical" href={canonical} />

Ativos e limites de deploy

Prefira src/assets/ e Image de astro:assets para imagens que se beneficiam de processamento. Mantenha ativos que exigem URLs inalteradas, robots.txt e ícones em public/; <img> comum é válido para casos deliberados de passagem/remota. Forneça alt significativo (vazio para imagens decorativas) e dimensões intrínsecas ou restrições de layout equivalentes. Corresponda as APIs de imagem responsiva à versão instalada e evite carregar ansiosamente toda imagem; priorize apenas imagens críticas genuinamente acima da dobra. Verifique os serviços de imagem SSR e seus requisitos de tempo de execução/custo antes de habilitá-los.

Use os mecanismos de cabeçalhos/redirecionamentos do host existente apenas quando necessário. _headers e _redirects são específicos do provedor, não requisitos universais do Astro. Para SSR de adaptador, siga a saída gerada dessa versão do adaptador e as convenções de vínculo de tempo de execução, em vez de uma configuração estática/SPA genérica escrita manualmente.

Verificação e relatório

Use os scripts de verificação/build/teste existentes do repositório quando autorizado. Verifique a tipagem de props, rotas emitidas, validação de coleção, exposição de página de rascunho, links de alternância de localidade, origem canônica/remoção de query, comportamento de base/barra, status de rota desconhecida, comportamento de teclado e erros de console do navegador. Uma build estática bem-sucedida não prova compatibilidade de tempo de execução SSR ou redirecionamentos de produção. Relate comandos realmente executados, suposições de versão, integrações ausentes/fixtures de conteúdo e comportamento de hospedagem não verificado. Não instale, faça deploy ou dispare serviços remotos como uma etapa de verificação implícita.

Fontes e proveniência

Esta é a síntese do autor, não uma cópia em massa de skills de terceiros. Leia apenas a documentação relevante para a tarefa e versão instalada:

• Astro Oficial: componentes e props, scripts do navegador, renderização sob demanda.
• Astro Oficial: Coleções de Conteúdo, migração para Astro 5, roteamento i18n, adaptador Cloudflare.
• astrolicious/agent-skills é uma referência da comunidade, não documentação oficial do Astro ou garantia de compatibilidade. Consulte-a seletivamente; a documentação oficial da API correspondente à versão tem precedência.