Construtor de Sites Astro
Esta habilidade ajuda você a construir sites com Astro.build, guiando-o pela seleção de temas, acesso à documentação e melhores práticas de desenvolvimento. Use esta habilidade sempre que um usuário mencionar construir com Astro, quiser criar um site ou precisar de ajuda com recursos específicos do Astro.
Quando Usar Esta Habilidade
Ative esta habilidade quando:
- O usuário mencionar "Astro" ou "astro.build" em sua solicitação
- O usuário quiser construir um site e Astro for apropriado (blogs, documentação, portfólios, sites de marketing, etc.)
- O usuário precisar selecionar um tema para seu projeto Astro
- O usuário precisar de ajuda com componentes Astro, roteamento ou configuração
- O usuário quiser integrar React, Vue ou outros frameworks com Astro
- O usuário precisar de acesso à documentação ou às melhores práticas do Astro
Visão Geral do Fluxo de Trabalho
Ao construir um site Astro, siga este processo:
- Entender Requisitos - Determinar o tipo de site e os recursos necessários
- Selecionar Tema Apropriado - Escolher entre os temas gratuitos do Astro com base nos requisitos
- Acessar Documentação - Referenciar a documentação do Astro para recursos específicos
- Inicializar Projeto - Configurar a estrutura do projeto
- Desenvolver Componentes - Construir usando a arquitetura de componentes do Astro
- Otimizar e Implantar - Seguir as melhores práticas de performance
Etapa 1: Entender Requisitos
Primeiro, identifique o tipo de site e seus requisitos:
Tipos de Site:
- Blog/Site de publicação
- Portfólio/Vitrines
- Site de documentação
- Site de marketing/Landing page
- Site de e-commerce
- Site empresarial/Comercial
- Site pessoal
Perguntas-chave a Fazer:
- Qual é o propósito principal do site?
- Que tipos de conteúdo ele terá? (postagens de blog, projetos, produtos, etc.)
- Ele precisa de interatividade? (formulários, busca, conteúdo dinâmico)
- Quais frameworks o usuário prefere? (React, Vue, Svelte, etc.)
- Precisa de recursos específicos? (modo escuro, i18n, integração com CMS)
Etapa 2: Selecionar Tema Apropriado
Use web_fetch para navegar por temas gratuitos compatíveis com React:
URL: https://astro.build/themes/1/?search=&technology%5B%5D=react&price%5B%5D=free
Critérios de Seleção de Tema:
Para Blogs/Publicações:
- Procure temas com tipografia forte
- Deve suportar Markdown/MDX
- Deve ter tags/categorias
- Suporte a feed RSS
- Considere: astro-paper, astro-blog-template
Para Portfólios:
- Vitrine visual de projetos
- Seções Sobre/Contato
- Animações suaves
- Considere: astro-portfolio, temas de portfólio pessoal
Para Documentação:
- Use Starlight (framework oficial de documentação do Astro)
- Recursos: Busca, navegação lateral, modo escuro, i18n
- Melhor para: Documentação técnica, referências de API, guias
Para Landing Pages:
- Seção de herói com CTA
- Seções de Recursos/Benefícios
- Formulários de contato
- Otimizado para conversão
Para E-commerce:
- Listagem de produtos e filtros
- Funcionalidade de carrinho de compras
- Pronto para integração de pagamento
- Páginas de detalhes do produto
Ação: Busque a página de temas, analise os temas disponíveis e recomende 2-3 opções que melhor atendam aos requisitos do usuário. Explique por que cada tema é adequado.
Etapa 3: Acessar Documentação do Astro
Quando você precisar de documentação específica do Astro, consulte:
- Referência Interna:
references/astro_docs.md- Contém conceitos principais do Astro, sintaxe e padrões comuns - Documentação Completa: Buscar em
https://docs.astro.build/llms-full.txtpara informações abrangentes
Quando Consultar a Documentação:
- Dúvidas sobre sintaxe de componentes → Consultar astro_docs.md
- Roteamento e páginas → Consultar astro_docs.md
- Opções de estilo → Consultar astro_docs.md
- Recursos avançados → Buscar em docs.astro.build
- Configuração de integrações → Buscar em docs.astro.build
- Detalhes de API → Buscar em docs.astro.build
Etapa 4: Inicializar Projeto Astro
Usando o CLI Create Astro
# Criar novo projeto
npm create astro@latest
# Ou com um template específico
npm create astro@latest -- --template <tema-github-usuario>/<tema-repositorio>
Configuração da Estrutura do Projeto
Após a inicialização, garanta a estrutura adequada:
projeto/
├── src/
│ ├── components/ # Componentes reutilizáveis
│ ├── layouts/ # Layouts de página
│ ├── pages/ # Rotas (OBRIGATÓRIO)
│ │ └── index.astro # Página inicial
│ ├── content/ # Coleções de conteúdo (opcional)
│ └── assets/ # Imagens otimizadas
├── public/ # Ativos estáticos
├── astro.config.mjs # Configuração
├── package.json
└── tsconfig.json
Crítico: O diretório src/pages/ é OBRIGATÓRIO para o funcionamento do roteamento.
Etapa 5: Desenvolver Componentes e Páginas
Padrão de Desenvolvimento de Componentes
- Criar arquivo de componente em
src/components/ - Definir interface de props (se estiver usando TypeScript)
- Escrever script do componente (executa em tempo de build)
- Criar template (HTML com sintaxe Astro)
- Adicionar estilos com escopo (opcional)
Exemplo:
---
interface Props {
titulo: string;
descricao?: string;
}
const { titulo, descricao } = Astro.props;
---
<article>
<h2>{titulo}</h2>
{descricao && <p>{descricao}</p>}
</article>
<style>
article {
padding: 1rem;
border: 1px solid #ccc;
}
</style>
Padrão de Desenvolvimento de Páginas
- Criar arquivo de página em
src/pages/(determina a rota) - Importar componentes e layouts necessários
- Definir getStaticPaths() para rotas dinâmicas
- Compor página usando componentes
Exemplo de página:
---
import Layout from '../layouts/Layout.astro';
import Hero from '../components/Hero.astro';
const titulo = "Minha Página";
---
<Layout title={titulo}>
<Hero />
<!-- Mais conteúdo -->
</Layout>
Adicionando Interatividade
Quando você precisar de interatividade no lado do cliente:
- Instalar integração de framework:
npx astro add react - Criar componente de framework (.jsx, .vue, .svelte)
- Importar e usar com diretiva cliente:
---
import ReactComponent from '../components/ReactComponent.jsx';
---
<!-- Estático (sem JS) -->
<ReactComponent />
<!-- Interativo -->
<ReactComponent client:load />
<!-- Opções: client:idle, client:visible, client:media -->
Etapa 6: Consultar Documentação Conforme Necessário
Antes de escrever código, leia as seções relevantes de references/astro_docs.md:
- Dúvidas sobre componentes → Ler seção "Sintaxe de Componentes"
- Problemas de roteamento → Ler seção "Roteamento"
- Estilo → Ler seção "Estilo"
- Imagens → Ler seção "Imagens e Ativos"
- Configuração → Ler seção "Configuração"
Para tópicos avançados, busque a documentação completa:
web_fetch: https://docs.astro.build/llms-full.txt
Melhores Práticas
Otimização de Performance
- Mantenha componentes estáticos por padrão - Adicione
client:*apenas quando realmente necessário - Use o componente Image do Astro - Otimização automática
- Aproveite a arquitetura de ilhas - JavaScript mínimo por padrão
- Divisão de código - Astro divide automaticamente por página
Fluxo de Trabalho de Desenvolvimento
- Comece com a estrutura - Configure layouts e páginas básicas primeiro
- Orientado a componentes - Construa componentes reutilizáveis
- Segurança de tipos - Use TypeScript para props e melhor experiência de desenvolvimento
- Coleções de Conteúdo - Para gerenciamento de conteúdo com segurança de tipos
- Teste localmente - Execute
npm run devcom frequência
Padrões Comuns a Seguir
- Use layouts para estrutura de página consistente
- Crie componente SEO para meta tags
- Configure interfaces TypeScript adequadas
- Implemente páginas de erro apropriadas (404, 500)
- Adicione texto alternativo correto às imagens
- Use HTML semântico
Solução de Problemas
Problemas Comuns
"Módulo não encontrado"
- Verifique caminhos de importação corretos
- Confirme que as integrações estão instaladas
- Verifique se
astro.config.mjstem a configuração de integração correta
"Página não renderizando"
- Verifique se o arquivo está no diretório
src/pages/ - Verifique erros de sintaxe no frontmatter
- Garanta extensão de arquivo correta (.astro, .md, .mdx)
"Estilos não sendo aplicados"
- Estilos com escopo se aplicam apenas ao HTML do próprio componente
- Use
is:globalpara estilos globais - Verifique a configuração do Tailwind se estiver usando Tailwind
"Componente não interativo"
- Adicione diretiva
client:*aos componentes de framework - Garanta que a integração esteja instalada (ex.:
@astrojs/react) - Verifique o console do navegador para erros de JavaScript
Recursos
Scripts
scripts/theme_analyzer.py- Ajuda a buscar e analisar temas do Astro na página oficial de temas. Use para explorar opções de tema programaticamente com base em filtros de tecnologia e preço.
Referências
references/astro_docs.md- LEIA ISTO PRIMEIRO para conceitos principais do Astro, sintaxe de componentes, roteamento, estilo e padrões comuns. Esta é sua referência principal para desenvolvimento Astro.
Recursos Externos
- Temas Astro: https://astro.build/themes/
- Documentação Astro (amigável para LLM): https://docs.astro.build/llms-full.txt
- Documentação Astro: https://docs.astro.build
- Discord Astro: https://astro.build/chat
Exemplos de Fluxo de Trabalho
Exemplo 1: Construindo um Blog
Usuário: "Quero construir um blog com Astro e React"
Fluxo de trabalho:
- Identificar requisitos: Site de blog, precisa de suporte React, quer tema gratuito
- Buscar temas:
web_fetch https://astro.build/themes/1/?technology%5B%5D=react&price%5B%5D=free - Recomendar tema: Sugerir 2-3 temas orientados a blog com explicações
- Ler
references/astro_docs.mdpara consultar padrões de componentes - Orientar configuração: Fornecer comandos de instalação e estrutura
- Ajudar na construção: Criar layout de postagem de blog, página de listagem, páginas de postagem individuais
- Adicionar interatividade: Mostrar como adicionar componentes React com
client:loadpara recursos como comentários
Exemplo 2: Site de Portfólio
Usuário: "Crie um site de portfólio para mim usando https://astro.build/"
Fluxo de trabalho:
- Esclarecer requisitos: O que mostrar (projetos, habilidades, experiência?)
- Buscar temas de portfólio na página de temas do Astro
- Recomendar a melhor correspondência com base na área do usuário (desenvolvedor, designer, etc.)
- Ler sintaxe de componentes de
references/astro_docs.md - Configurar estrutura do projeto com o tema selecionado
- Criar/personalizar componentes (Hero, Grade de Projetos, Sobre, Contato)
- Adicionar transições suaves se necessário
- Otimizar imagens usando o componente Image do Astro
Exemplo 3: Site de Documentação
Usuário: "Preciso de um site de documentação com busca e modo escuro"
Fluxo de trabalho:
- Identificar: Site de documentação, precisa de busca e modo escuro
- Recomendar Starlight (framework oficial de documentação do Astro)
- Mostrar configuração:
npm create astro@latest -- --template starlight - Consultar documentação do Starlight na documentação completa do Astro
- Configurar estrutura de navegação lateral
- Configurar estrutura de conteúdo
- Ativar modo escuro (integrado)
- Configurar busca (integrada com Pagefind)
Lembretes Principais
- Sempre leia
references/astro_docs.mdPRIMEIRO antes de responder perguntas sobre componentes ou sintaxe - Busque temas na página de temas do Astro quando o usuário precisar de um ponto de partida
- Use web_fetch para documentação completa quando necessário
- Mantenha simples - Astro foi projetado para ser direto; não complique demais
- Arquitetura de ilhas - Lembre-se de que os componentes são estáticos por padrão
- Segurança de tipos - Incentive o uso de TypeScript para melhor experiência de desenvolvimento
Critérios de Sucesso
Um projeto Astro está configurado corretamente quando:
- ✅ A estrutura do projeto segue as convenções do Astro
- ✅ O diretório
src/pages/existe com pelo menos index.astro - ✅ Tema apropriado selecionado com base nos requisitos
- ✅ Componentes seguem os padrões de sintaxe do Astro
- ✅ Interatividade no lado do cliente adicionada apenas onde necessário
- ✅ Interfaces TypeScript definidas para props de componentes
- ✅ Imagens otimizadas usando o componente Image do Astro
- ✅ O site é executado com sucesso com
npm run dev