Constructor de Sitios Web con Astro
Esta habilidad te ayuda a construir sitios web con Astro.build guiándote en la selección de temas, el acceso a la documentación y las mejores prácticas de desarrollo. Utiliza esta habilidad siempre que un usuario mencione construir con Astro, quiera crear un sitio web o necesite ayuda con funcionalidades específicas de Astro.
Cuándo Usar Esta Habilidad
Activa esta habilidad cuando:
- El usuario mencione "Astro" o "astro.build" en su solicitud
- El usuario quiera construir un sitio web y Astro sea apropiado (blogs, documentación, portafolios, sitios de marketing, etc.)
- El usuario necesite seleccionar un tema para su proyecto Astro
- El usuario necesite ayuda con componentes, enrutamiento o configuración de Astro
- El usuario quiera integrar React, Vue u otros frameworks con Astro
- El usuario necesite acceder a la documentación o mejores prácticas de Astro
Resumen del Flujo de Trabajo
Al construir un sitio web con Astro, sigue este proceso:
- Comprender los Requisitos - Determinar el tipo de sitio web y las funcionalidades necesarias
- Seleccionar el Tema Apropiado - Elegir de los temas gratuitos de Astro según los requisitos
- Acceder a la Documentación - Consultar la documentación de Astro para funcionalidades específicas
- Inicializar el Proyecto - Configurar la estructura del proyecto
- Desarrollar Componentes - Construir usando la arquitectura de componentes de Astro
- Optimizar e Implementar - Seguir las mejores prácticas de rendimiento
Paso 1: Comprender los Requisitos
Primero, identifica el tipo de sitio web y sus requisitos:
Tipos de Sitio Web:
- Blog/Sitio de publicaciones
- Portafolio/Vitrina
- Sitio de documentación
- Página de marketing/Landing page
- Sitio de comercio electrónico
- Sitio de empresa/negocio
- Sitio personal
Preguntas Clave a Realizar:
- ¿Cuál es el propósito principal del sitio?
- ¿Qué tipos de contenido tendrá? (publicaciones de blog, proyectos, productos, etc.)
- ¿Necesita interactividad? (formularios, búsqueda, contenido dinámico)
- ¿Qué frameworks prefiere el usuario? (React, Vue, Svelte, etc.)
- ¿Necesita funcionalidades específicas? (modo oscuro, i18n, integración con CMS)
Paso 2: Seleccionar el Tema Apropiado
Usa web_fetch para navegar por los temas gratuitos compatibles con React:
URL: https://astro.build/themes/1/?search=&technology%5B%5D=react&price%5B%5D=free
Criterios de Selección de Temas:
Para Blogs/Publicaciones:
- Busca temas con tipografía sólida
- Debe ser compatible con Markdown/MDX
- Debe tener etiquetas/categorías
- Compatibilidad con feed RSS
- Considera: astro-paper, astro-blog-template
Para Portafolios:
- Vitrina visual de proyectos
- Secciones Acerca de/Contacto
- Animaciones suaves
- Considera: astro-portfolio, temas de portafolio personal
Para Documentación:
- Usa Starlight (framework oficial de documentación de Astro)
- Funcionalidades: Búsqueda, barra lateral de navegación, modo oscuro, i18n
- Ideal para: Documentación técnica, referencias de API, guías
Para Páginas de Aterrizaje:
- Sección Hero con llamado a la acción (CTA)
- Secciones de funcionalidades/beneficios
- Formularios de contacto
- Optimizado para conversión
Para Comercio Electrónico:
- Listados de productos y filtros
- Funcionalidad de carrito de compras
- Listo para integración de pagos
- Páginas de detalle de producto
Acción: Obtén la página de temas, analiza los temas disponibles y recomienda 2-3 opciones que mejor se ajusten a los requisitos del usuario. Explica por qué cada tema es adecuado.
Paso 3: Acceder a la Documentación de Astro
Cuando necesites documentación específica de Astro, consulta:
- Referencia Incorporada:
references/astro_docs.md- Contiene conceptos centrales de Astro, sintaxis y patrones comunes - Documentación Completa: Obtén de
https://docs.astro.build/llms-full.txtpara información exhaustiva
Cuándo Consultar la Documentación:
- Preguntas sobre sintaxis de componentes → Consulta astro_docs.md
- Enrutamiento y páginas → Consulta astro_docs.md
- Opciones de estilo → Consulta astro_docs.md
- Funcionalidades avanzadas → Obtén de docs.astro.build
- Configuración de integraciones → Obtén de docs.astro.build
- Detalles de API → Obtén de docs.astro.build
Paso 4: Inicializar el Proyecto Astro
Usando el CLI Create Astro
# Crear nuevo proyecto
npm create astro@latest
# O con una plantilla específica
npm create astro@latest -- --template <theme-github-username>/<theme-repo>
Configuración de la Estructura del Proyecto
Después de la inicialización, asegura una estructura adecuada:
project/
├── src/
│ ├── components/ # Componentes reutilizables
│ ├── layouts/ # Diseños de página
│ ├── pages/ # Rutas (OBLIGATORIO)
│ │ └── index.astro # Página de inicio
│ ├── content/ # Colecciones de contenido (opcional)
│ └── assets/ # Imágenes optimizadas
├── public/ # Activos estáticos
├── astro.config.mjs # Configuración
├── package.json
└── tsconfig.json
Importante: El directorio src/pages/ es OBLIGATORIO para que el enrutamiento funcione.
Paso 5: Desarrollar Componentes y Páginas
Patrón de Desarrollo de Componentes
- Crear archivo de componente en
src/components/ - Definir interfaz de props (si usas TypeScript)
- Escribir script del componente (se ejecuta en tiempo de compilación)
- Crear plantilla (HTML con sintaxis de Astro)
- Agregar estilos con ámbito (opcional)
Ejemplo:
---
interface Props {
title: string;
description?: string;
}
const { title, description } = Astro.props;
---
<article>
<h2>{title}</h2>
{description && <p>{description}</p>}
</article>
<style>
article {
padding: 1rem;
border: 1px solid #ccc;
}
</style>
Patrón de Desarrollo de Páginas
- Crear archivo de página en
src/pages/(determina la ruta) - Importar componentes y diseños necesarios
- Definir getStaticPaths() para rutas dinámicas
- Componer la página usando componentes
Ejemplo de página:
---
import Layout from '../layouts/Layout.astro';
import Hero from '../components/Hero.astro';
const title = "Mi Página";
---
<Layout title={title}>
<Hero />
<!-- Más contenido -->
</Layout>
Agregar Interactividad
Cuando necesites interactividad del lado del cliente:
- Instalar integración del framework:
npx astro add react - Crear componente del framework (.jsx, .vue, .svelte)
- Importar y usar con directiva cliente:
---
import ReactComponent from '../components/ReactComponent.jsx';
---
<!-- Estático (sin JS) -->
<ReactComponent />
<!-- Interactivo -->
<ReactComponent client:load />
<!-- Opciones: client:idle, client:visible, client:media -->
Paso 6: Consultar Documentación Según Sea Necesario
Antes de escribir código, lee las secciones relevantes de references/astro_docs.md:
- Preguntas sobre componentes → Lee la sección "Sintaxis de Componentes"
- Problemas de enrutamiento → Lee la sección "Enrutamiento"
- Estilo → Lee la sección "Estilo"
- Imágenes → Lee la sección "Imágenes y Activos"
- Configuración → Lee la sección "Configuración"
Para temas avanzados, obtén la documentación completa:
web_fetch: https://docs.astro.build/llms-full.txt
Mejores Prácticas
Optimización del Rendimiento
- Mantén los componentes estáticos por defecto - Solo agrega
client:*cuando sea realmente necesario - Usa el componente Image de Astro - Optimización automática
- Aprovecha la arquitectura de islas - JavaScript mínimo por defecto
- División de código - Astro divide automáticamente por página
Flujo de Trabajo de Desarrollo
- Empieza con la estructura - Configura primero los diseños y las páginas básicas
- Impulsado por componentes - Construye componentes reutilizables
- Seguridad de tipos - Usa TypeScript para props y mejor experiencia de desarrollo
- Colecciones de contenido - Para gestión de contenido con verificación de tipos
- Prueba localmente - Ejecuta
npm run devcon frecuencia
Patrones Comunes a Seguir
- Usa diseños para una estructura de página consistente
- Crea un componente SEO para metaetiquetas
- Configura interfaces de TypeScript adecuadas
- Implementa páginas de error apropiadas (404, 500)
- Agrega texto alternativo adecuado a las imágenes
- Usa HTML semántico
Solución de Problemas
Problemas Comunes
"Módulo no encontrado"
- Asegúrate de que las rutas de importación sean correctas
- Verifica que las integraciones estén instaladas
- Revisa que
astro.config.mjstenga la configuración de integración correcta
"La página no se renderiza"
- Verifica que el archivo esté en el directorio
src/pages/ - Revisa si hay errores de sintaxis en el frontmatter
- Asegúrate de que la extensión del archivo sea correcta (.astro, .md, .mdx)
"Los estilos no se aplican"
- Los estilos con ámbito solo se aplican al HTML propio del componente
- Usa
is:globalpara estilos globales - Revisa la configuración de Tailwind si usas Tailwind
"El componente no es interactivo"
- Agrega la directiva
client:*a los componentes del framework - Asegúrate de que la integración esté instalada (ej.,
@astrojs/react) - Revisa la consola del navegador en busca de errores de JavaScript
Recursos
Scripts
scripts/theme_analyzer.py- Ayuda a obtener y analizar temas de Astro desde la página oficial de temas. Úsalo para explorar opciones de temas de manera programática según filtros de tecnología y precio.
Referencias
references/astro_docs.md- LÉELO PRIMERO para conceptos centrales de Astro, sintaxis de componentes, enrutamiento, estilo y patrones comunes. Esta es tu referencia principal para el desarrollo con Astro.
Recursos Externos
- Temas de Astro: https://astro.build/themes/
- Documentación de Astro (amigable para LLM): https://docs.astro.build/llms-full.txt
- Documentación de Astro: https://docs.astro.build
- Discord de Astro: https://astro.build/chat
Ejemplos de Flujos de Trabajo
Ejemplo 1: Construir un Blog
Usuario: "Quiero construir un blog con Astro y React"
Flujo de trabajo:
- Identificar requisitos: Sitio de blog, necesita compatibilidad con React, quiere un tema gratuito
- Obtener temas:
web_fetch https://astro.build/themes/1/?technology%5B%5D=react&price%5B%5D=free - Recomendar tema: Sugerir 2-3 temas orientados a blogs con explicaciones
- Leer
references/astro_docs.mdpara consultar patrones de componentes - Guiar la configuración: Proporcionar comandos de instalación y estructura
- Ayudar a construir: Crear diseño de entrada de blog, página de listado, páginas de entrada individual
- Agregar interactividad: Mostrar cómo agregar componentes de React con
client:loadpara funcionalidades como comentarios
Ejemplo 2: Sitio de Portafolio
Usuario: "Crea un sitio de portafolio para mí usando https://astro.build/"
Flujo de trabajo:
- Aclarar requisitos: ¿Qué mostrar (proyectos, habilidades, experiencia)?
- Obtener temas de portafolio de la página de temas de Astro
- Recomendar la mejor opción según el campo del usuario (desarrollador, diseñador, etc.)
- Leer la sintaxis de componentes de
references/astro_docs.md - Configurar la estructura del proyecto con el tema seleccionado
- Crear/personalizar componentes (Hero, Cuadrícula de proyectos, Acerca de, Contacto)
- Agregar transiciones suaves si es necesario
- Optimizar imágenes usando el componente Image de Astro
Ejemplo 3: Sitio de Documentación
Usuario: "Necesito un sitio de documentación con búsqueda y modo oscuro"
Flujo de trabajo:
- Identificar: Sitio de documentación, necesita búsqueda y modo oscuro
- Recomendar Starlight (framework oficial de documentación de Astro)
- Mostrar configuración:
npm create astro@latest -- --template starlight - Consultar la documentación de Starlight desde la documentación completa de Astro
- Configurar la estructura de navegación de la barra lateral
- Configurar la estructura de contenido
- Habilitar modo oscuro (incorporado)
- Configurar búsqueda (incorporada con Pagefind)
Recordatorios Clave
- Lee SIEMPRE
references/astro_docs.mdPRIMERO antes de responder preguntas sobre componentes o sintaxis - Obtén temas de la página de temas de Astro cuando el usuario necesite un punto de partida
- Usa web_fetch para la documentación completa cuando sea necesario
- Mantenlo simple - Astro está diseñado para ser directo; no compliques de más
- Arquitectura de islas - Recuerda que los componentes son estáticos por defecto
- Seguridad de tipos - Fomenta el uso de TypeScript para una mejor experiencia de desarrollo
Criterios de Éxito
Un proyecto Astro está configurado correctamente cuando:
- ✅ La estructura del proyecto sigue las convenciones de Astro
- ✅ El directorio
src/pages/existe con al menos un index.astro - ✅ Se seleccionó un tema apropiado según los requisitos
- ✅ Los componentes siguen los patrones de sintaxis de Astro
- ✅ La interactividad del lado del cliente solo se agrega donde es necesario
- ✅ Se definieron interfaces de TypeScript para las props de los componentes
- ✅ Las imágenes se optimizan usando el componente Image de Astro
- ✅ El sitio se ejecuta correctamente con
npm run dev