Communitygithub.com

ASoudy/AGS

Construa sites focados em conteúdo com Astro — zero JavaScript por padrão, arquitetura de ilhas, componentes multi-framework e suporte a Markdown/MDX.

O que é AGS?

Astro é um framework web moderno projetado para construir sites ricos em conteúdo, como blogs, documentações, portfólios e sites de marketing. Sua principal inovação é a **Arquitetura de Ilhas**: por padrão, Astro envia zero JavaScript para o navegador, hidratando componentes interativos seletivamente como 'ilhas' isoladas. Esta habilidade (ASoudy/AGS) orienta o uso de Astro, explicando desde a configuração inicial do projeto até recursos avançados como coleções de conteúdo com tipagem segura, roteamento baseado em arquivos e hidratação seletiva com diretivas `client:`. É ideal para desenvolvedores que priorizam desempenho, Core Web Vitals e SEO, suportando frameworks como React, Vue e Svelte no mesmo projeto. A documentação, baseada no SKILL.md, fornece exemplos práticos, melhores práticas e armadilhas comuns, garantindo que o usuário entenda como criar sites estáticos (SSG) ou com renderização dinâmica (SSR) de forma eficiente.

Funciona com✓Claude Code~Codex CLI✓Cursor✓Gemini CLI
npx skills add https://github.com/ASoudy/AGS/tree/HEAD/AGAS/plugins/antigravity-awesome-skills-claude/skills/astro

Perguntar na sua IA favorita

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

Documentação

Astro Web Framework

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 central é a Arquitetura de Ilhas: por padrão, Astro envia zero JavaScript para o navegador. Componentes interativos são hidratados seletivamente como "ilhas" isoladas. Astro suporta React, Vue, Svelte, Solid e outros frameworks de UI simultaneamente no mesmo projeto, permitindo escolher a ferramenta certa para cada componente.

Quando Usar Esta Habilidade

  • Use ao construir um blog, site de documentação, página de marketing ou portfólio
  • Use quando desempenho e Core Web Vitals são a prioridade máxima
  • Use quando o projeto é pesado em conteúdo com arquivos Markdown ou MDX
  • Use quando você deseja 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           # Suporte a React
npx astro add mdx             # Suporte a MDX
npx astro add sitemap         # sitemap.xml automático
npx astro add vercel          # Adaptador SSR para Vercel

Estrutura do projeto:

src/
  pages/          ← Roteamento baseado em arquivos (.astro, .md, .mdx)
  layouts/        ← Estruturas de página reutilizáveis
  components/     ← Componentes de UI (.astro, .tsx, .vue, etc.)
  content/        ← Coleções de conteúdo com tipagem segura (Markdown/MDX)
  styles/         ← CSS global
public/           ← Ativos estáticos (copiados como estão)
astro.config.mjs  ← Configuração do framework

Passo 2: Sintaxe de Componente Astro

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

---
// src/components/Card.astro
// Este bloco é executado APENAS no servidor — nunca no navegador
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>
  /* Escopo automático para este componente */
  .card { border: 1px solid #eee; padding: 1rem; }
</style>

Passo 3: Páginas e Roteamento Baseado em Arquivos

src/pages/index.astro          → /
src/pages/about.astro          → /about
src/pages/blog/[slug].astro    → /blog/:slug (dinâmico)
src/pages/blog/[...path].astro → /blog/* (abrangente)

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 fornecem acesso com tipagem segura 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 são renderizados como HTML estático sem JavaScript. Use diretivas client: para hidratar:

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

<!-- HTML estático — nenhum JavaScript enviado ao navegador -->
<Counter initialCount={0} />

<!-- Hidrata imediatamente ao carregar a página -->
<Counter initialCount={0} client:load />

<!-- Hidrata quando o componente entra na viewport -->
<VideoPlayer src="/demo.mp4" client:visible />

<!-- Hidrata apenas quando o navegador está ocioso -->
<Analytics client:idle />

<!-- Hidrata apenas em uma media query específica -->
<MobileMenu client:media="(max-width: 768px)" />

Passo 6: Layouts

---
// src/layouts/BaseLayout.astro
interface Props {
  title: string;
  description?: string;
}
const { title, description = 'Meu Site Astro' } = Astro.props;
---

<html lang="pt-BR">
  <head>
    <meta charset="utf-8" />
    <title>{title}</title>
    <meta name="description" content={description} />
  </head>
  <body>
    <nav>...</nav>
    <main>
      <slot />  <!-- o conteúdo da página é renderizado aqui -->
    </main>
    <footer>...</footer>
  </body>
</html>
---
// src/pages/about.astro
import BaseLayout from '../layouts/BaseLayout.astro';
---

<BaseLayout title="Sobre Nós">
  <h1>Sobre Nós</h1>
  <p>Bem-vindo à nossa empresa...</p>
</BaseLayout>

Passo 7: Modo SSR (Renderização Sob Demanda)

Ative SSR para páginas dinâmicas configurando um adaptador:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  output: 'hybrid',  // 'static' | 'server' | 'hybrid'
  adapter: vercel(),
});

Opte por páginas individuais para SSR com export const prerender = false.

Exemplos

Exemplo 1: Blog com Feed RSS

// src/pages/rss.xml.ts
import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';

export async function GET(context) {
  const posts = await getCollection('blog');
  return rss({
    title: 'Meu Blog',
    description: 'Posts mais recentes',
    site: context.site,
    items: posts.map(post => ({
      title: post.data.title,
      pubDate: post.data.date,
      link: `/blog/${post.slug}/`,
    })),
  });
}

Exemplo 2: Endpoint de API (SSR)

// src/pages/api/subscribe.ts
import type { APIRoute } from 'astro';

export const POST: APIRoute = async ({ request }) => {
  const { email } = await request.json();

  if (!email) {
    return new Response(JSON.stringify({ error: 'Email é obrigatório' }), {
      status: 400,
      headers: { 'Content-Type': 'application/json' },
    });
  }

  await addToNewsletter(email);
  return new Response(JSON.stringify({ success: true }), { status: 200 });
};

Exemplo 3: Componente React como Ilha

// src/components/SearchBox.tsx
import { useState } from 'react';

export default function SearchBox() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);

  async function search(e: React.FormEvent) {
    e.preventDefault();
    const data = await fetch(`/api/search?q=${query}`).then(r => r.json());
    setResults(data);
  }

  return (
    <form onSubmit={search}>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      <button type="submit">Buscar</button>
      <ul>{results.map(r => <li key={r.id}>{r.title}</li>)}</ul>
    </form>
  );
}
---
import SearchBox from '../components/SearchBox.tsx';
---
<!-- Hidratado imediatamente — esta ilha é interativa -->
<SearchBox client:load />

Melhores Práticas

  • ✅ Mantenha a maioria dos componentes como arquivos .astro estáticos — hidrate apenas o que precisa ser interativo
  • ✅ Use coleções de conteúdo para todo conteúdo Markdown/MDX — você ganha tipagem segura e validação automática
  • ✅ Prefira client:visible em vez de client:load para componentes abaixo da dobra para reduzir o JavaScript inicial
  • ✅ Use import.meta.env para variáveis de ambiente — prefixe variáveis públicas com PUBLIC_
  • ✅ Adicione <ViewTransitions /> de astro:transitions para navegação suave entre páginas sem um SPA completo
  • ❌ Não use client:load em todos os componentes — isso anula a vantagem de desempenho do Astro
  • ❌ Não coloque segredos no frontmatter de .astro que seja usado em templates voltados ao cliente
  • ❌ Não pule getStaticPaths para rotas dinâmicas no modo estático — as builds falharão

Notas de Segurança e Segurança

  • O código do frontmatter em arquivos .astro é executado apenas no servidor e nunca é exposto ao navegador.
  • Use import.meta.env.PUBLIC_* apenas para valores não sensíveis. Variáveis de ambiente privadas (sem prefixo PUBLIC_) nunca são enviadas ao cliente.
  • Ao usar o modo SSR, valide todas as entradas de Astro.request antes de consultas ao banco de dados ou chamadas de API.
  • Sanitize qualquer conteúdo fornecido pelo usuário antes de renderizar com set:html — ele ignora o escape automático.

Armadilhas Comuns

  • Problema: O JavaScript de um componente React/Vue não é executado no navegador Solução: Adicione uma diretiva client: (client:load, client:visible, etc.) — sem ela, os componentes são renderizados apenas como HTML estático.

  • Problema: Os dados de getStaticPaths estão desatualizados após atualizações de conteúdo durante o desenvolvimento Solução: O servidor de desenvolvimento do Astro observa arquivos de conteúdo — reinicie se as alterações em content/config.ts não forem refletidas.

  • Problema: O tipo de Astro.props é any — sem autocomplete Solução: Defina uma interface ou tipo Props no frontmatter e o Astro o inferirá automaticamente.

  • Problema: O CSS de um componente .astro vaza para outros componentes Solução: Estilos em tags <style> de .astro têm escopo automático. Use :global() apenas quando intencionalmente visar componentes filhos.

Habilidades Relacionadas

  • @sveltekit — Quando você precisa de um framework full-stack com UI reativa (vs. o foco em conteúdo do Astro)
  • @nextjs-app-router-patterns — Quando você precisa de um framework full-stack focado em React
  • @tailwind-patterns — Estilizando sites Astro com Tailwind CSS
  • @progressive-web-app — Adicionando capacidades PWA a um site Astro

Limitações

  • Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo descrito acima.
  • Não trate a saída como substituta para validação específica de ambiente, testes ou revisão especializada.
  • Pare e peça esclarecimentos se entradas necessárias, permissões, limites de segurança ou critérios de sucesso estiverem faltando.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ASoudy/AGS

Advanced JavaScript animation library skill for creating complex, high-performance web animations.

ASoudy/AGS

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis.

ASoudy/AGS

One sentence - what this skill does and when to invoke it

ASoudy/AGS

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

ASoudy/AGS

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

ASoudy/AGS

Pull a YouTube video transcript into a queryable markdown vault with yt-dlp subtitle discovery, VTT cleanup, metadata frontmatter, and capture-seed stubs.

ASoudy/AGS

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

ASoudy/AGS

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

ASoudy/AGS

AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

ASoudy/AGS

CRITICAL: Use for Makepad animation system. Triggers on: makepad animation, makepad animator, makepad hover, makepad state, makepad transition, "from: { all: Forward", makepad pressed, makepad 动画, makepad 状态, makepad 过渡, makepad 悬停效果

ASoudy/AGS

Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.

ASoudy/AGS

Next.js App Router principles. Server Components, data fetching, routing patterns.

ASoudy/AGS

Expert integration of Supabase Auth with Next.js App Router

ASoudy/AGS

React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.

ASoudy/AGS

Best practices for Remotion - Video creation in React

ASoudy/AGS

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

ASoudy/AGS

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

ASoudy/AGS

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

ASoudy/AGS

Three.js animation - keyframe animation, skeletal animation, morph targets, animation mixing. Use when animating objects, playing GLTF animations, creating procedural motion, or blending animations.

ASoudy/AGS

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

Habilidades Relacionadas