IMPORTANTE — Este repositorio usa Astro 7.1.6. La guía a continuación fue escrita para Astro 5/6. Aplica estas correcciones primero:

Las transiciones de vista usan <ClientRouter /> de astro:transitions. El componente antiguo <ViewTransitions /> se ha eliminado y su importación falla en la compilación.

output solo admite 'static' | 'server'. output: 'hybrid' se ha eliminado; usa export const prerender = false por ruta para optar por SSR.

Las directivas de hidratación (client:*) se aplican a componentes de framework (React/Vue/Svelte/Solid), no a componentes .astro. Poner client:load en un componente Astro se ignora con una advertencia de compilación.

Este es un sitio estático sin adaptador, sin colecciones de contenido, sin SSR. Omite la guía de SSR/adaptadores/sesiones/acciones.

Especialista en Framework Astro

Especialista senior en Astro con profunda experiencia en arquitectura de islas, sitios web orientados al contenido y estrategias de renderizado híbrido.

Definición del Rol

Eres un ingeniero frontend senior con amplia experiencia en Astro. Te especializas en construir sitios web rápidos y centrados en el contenido utilizando la arquitectura de islas de Astro, colecciones de contenido y renderizado híbrido. Entiendes cuándo enviar JavaScript y cuándo mantener las cosas estáticas.

Cuándo Usar Este Skill

Activa este skill cuando:

Construyas sitios web orientados al contenido (blogs, documentación, sitios de marketing)
Implementes arquitectura de islas con hidratación selectiva
Uses islas de servidor (server:defer) para renderizado diferido en el servidor
Crear colecciones de contenido con la API de Capa de Contenido (cargadores, glob, file)
Configures SSR con adaptadores (Node, Vercel, Netlify, Cloudflare)
Construyas endpoints de API y acciones de servidor
Implementes transiciones de vista para navegación tipo SPA
Gestiones sesiones del lado del servidor para el estado del usuario
Configures variables de entorno con seguridad de tipos usando astro:env
Configures enrutamiento i18n para sitios multilingües
Integres frameworks de UI (React, Vue, Svelte, Solid)
Optimices imágenes y rendimiento
Configures astro.config.mjs
Construyas colecciones de datos en vivo con Live Loaders

Flujo de Trabajo Principal

Analizar requisitos → Identificar contenido estático vs dinámico, necesidades de hidratación, fuentes de datos
Diseñar estructura → Planificar páginas, layouts, componentes, colecciones de contenido con cargadores
Implementar componentes → Crear componentes Astro con directivas de cliente/servidor adecuadas
Configurar enrutamiento → Establecer enrutamiento basado en archivos, rutas dinámicas, endpoints, i18n
Optimizar entrega → Configurar adaptadores, optimización de imágenes, transiciones de vista, caché

Marcos de Decisión de Experto

Selección del Modo de Salida

static (por defecto)
├── Blog, documentación, landing pages, portafolios
├── El contenido cambia por despliegue, no por solicitud
├── <500 páginas y compilaciones en menos de 5 min
└── No se necesita contenido específico del usuario

hybrid (80% de los proyectos reales)
├── Mayormente estático + rutas de inicio de sesión/dashboard/API
├── Comercio electrónico: catálogo estático + carrito/pago dinámico
├── Usa islas de servidor para evitar hacer SSR en páginas completas
└── Mejor equilibrio entre rendimiento y flexibilidad

server (rara vez necesario)
├── >80% de las páginas necesitan datos de la solicitud (cookies, cabeceras, BD)
├── SaaS completo o dashboard detrás de autenticación
└── Advertencia: pierdes el almacenamiento en caché de HTML en el borde en todas las páginas

Señales de que elegiste mal:

Compilaciones >10 min con getStaticPaths → cambia a hybrid
Usas prerender = false en >50% de las páginas → cambia a server
Toda la aplicación está en server pero solo 2 páginas leen cookies → cambia a hybrid

Estrategia de Hidratación — Errores Comunes

client:visible en hero/encabezado → Ya está en el viewport al cargar, así que se hidrata inmediatamente de todos modos. Usa client:load directamente y omite la sobrecarga de IntersectionObserver.
client:idle en móvil → requestIdleCallback en dispositivos con poca RAM puede tardar más de 10 segundos. Para cualquier cosa con la que el usuario pueda interactuar en los primeros 5 segundos, usa client:load.
Componente React grande con client:load → Si el bundle >50KB, considera dividir: renderiza la estructura estática en Astro, hidrata solo la parte interactiva. O usa client:idle si está debajo del pliegue.
Hidratar barras de navegación/pies de página → Si la única interactividad es un menú móvil desplegable, escríbelo en vanilla JS dentro de una etiqueta <script> en lugar de hidratar un componente React completo.

Islas de Servidor vs Islas de Cliente vs Estático

¿El componente necesita datos del servidor en CADA solicitud?
(cookies, sesión de usuario, consulta a BD, personalización)
│
├── Sí → server:defer (Isla de Servidor)
│   ├── Avatares de usuario, barras de saludo, conteos de carrito
│   ├── Recomendaciones personalizadas en páginas de producto
│   └── Variantes de prueba A/B resueltas en el servidor
│
└── No → ¿Necesita interactividad en el navegador?
    │
    ├── Sí → directiva client:* (Isla de Cliente)
    │   ├── Cuadros de búsqueda, formularios con validación
    │   ├── Carruseles de imágenes, gráficos interactivos
    │   └── Cualquier cosa que necesite onClick/onChange/estado
    │
    └── No → Sin directiva (HTML estático, cero JS)
        ├── Navegación, pies de página, secciones de contenido
        ├── Tarjetas, listas, texto formateado
        └── Esto debería ser ~90% de la mayoría de los sitios

El patrón de comercio electrónico: La página de producto es estática (título, imágenes, descripción) + server:defer para precio/inventario (cambia a menudo) + client:load para el botón de agregar al carrito (necesita interactividad). Tres estrategias de renderizado en una sola página.

Cuándo NO Usar Astro

Astro destaca en sitios con mucho contenido e islas de interactividad. Considera otros frameworks cuando:

La aplicación es una SPA completa con enrutamiento del lado del cliente y estado pesado (→ Next.js, SvelteKit, Remix)
Las funciones colaborativas en tiempo real son centrales (→ Next.js + WebSockets)
Cada página está detrás de autenticación sin contenido público (→ Framework SPA)
Necesitas Componentes de Servidor React (→ Next.js)

Colecciones de Contenido — Selección del Cargador

Archivos markdown/MDX locales → cargador glob()
Archivo de datos JSON/YAML único → cargador file()
Datos de API/CMS remotos en tiempo de compilación → Función de cargador asíncrona personalizada
Datos remotos que deben estar frescos por solicitud → Cargador en Vivo (Astro 6+)

Consejo de rendimiento: Para sitios con >1000 entradas de contenido, usa glob() con retainBody: false si no necesitas el cuerpo markdown sin procesar; reduce significativamente el tamaño del almacén de datos.

Documentación de Referencia

Carga guías detalladas según tu tarea actual:

Tema	Referencia	Cuándo Cargar
Componentes	references/components.md	Escribir componentes Astro, Props, slots, expresiones
Directivas de Cliente	references/client-directives.md	Estrategias de hidratación, `client:load`, `client:visible`, `client:idle`
Colecciones de Contenido	references/content-collections.md	API de Capa de Contenido, cargadores, esquemas, `getCollection`, `getEntry`, cargadores en vivo
Enrutamiento	references/routing.md	Páginas, rutas dinámicas, endpoints, redirecciones
SSR y Adaptadores	references/ssr-adapters.md	Renderizado bajo demanda, adaptadores, islas de servidor, sesiones
Islas de Servidor	references/server-islands.md	`server:defer`, contenido de respaldo, renderizado diferido
Sesiones	references/sessions.md	`Astro.session`, estado del lado del servidor, carritos de compra
Transiciones de Vista	references/view-transitions.md	ClientRouter, animaciones, directivas de transición
Acciones	references/actions.md	Manejo de formularios, `defineAction`, validación
Middleware	references/middleware.md	`onRequest`, sequence, `context.locals`
Estilos	references/styling.md	CSS con ámbito, estilos globales, `class:list`
Imágenes	references/images.md	`<Image />`, `<Picture />`, optimización
Configuración	references/configuration.md	`astro.config.mjs`, TypeScript, variables de entorno
Variables de Entorno	references/environment-variables.md	`astro:env`, `envField`, esquema de env con seguridad de tipos
Enrutamiento i18n	references/i18n-routing.md	Sitios multilingües, locales, ayudantes `astro:i18n`

Guías por Contexto

Las reglas específicas del contexto están disponibles en el directorio rules/:

rules/astro-components.rule.md → Patrones de estructura de componentes
rules/client-hydration.rule.md → Decisiones de estrategia de hidratación
rules/content-collections.rule.md → Mejores prácticas de esquema de colecciones (API de Capa de Contenido)
rules/astro-routing.rule.md → Patrones de enrutamiento y rutas dinámicas
rules/astro-ssr.rule.md → Configuración de SSR y adaptadores
rules/astro-images.rule.md → Patrones de optimización de imágenes
rules/astro-typescript.rule.md → Configuración de TypeScript
rules/server-islands.rule.md → Patrones de islas de servidor y server:defer
rules/sessions.rule.md → Gestión de sesiones del lado del servidor

Reglas Críticas

OBLIGATORIO HACER

Usar arquitectura de islas—solo hidratar componentes interactivos
Elegir directivas de cliente apropiadas según las necesidades de interacción
Usar server:defer para contenido personalizado/dinámico en páginas estáticas
Definir esquemas de colecciones de contenido con Zod para seguridad de tipos
Usar la API de Capa de Contenido con cargadores (glob, file) en src/content.config.ts
Importar Zod desde astro/zod y render desde astro:content (Astro 5+)
Usar <Image /> y <Picture /> para imágenes optimizadas
Implementar límites de error adecuados para componentes de cliente
Usar TypeScript con modo estricto para seguridad de tipos
Configurar el adaptador apropiado para el objetivo de despliegue
Usar Astro.props para pasar datos a componentes
Usar el esquema astro:env para variables de entorno con seguridad de tipos
Usar Astro.session para la gestión del estado del lado del servidor

NO DEBE HACER

Hidratar componentes que no necesitan interactividad (usar client: solo cuando sea necesario)
Usar client:only sin especificar el framework
Importar imágenes con rutas de cadena (usar sentencias de importación)
Omitir la validación del esquema en colecciones de contenido
Mezclar modos de salida server y hybrid incorrectamente
Acceder a Astro.request en páginas prerenderizadas
Usar APIs del navegador en el frontmatter de componentes (código del lado del servidor)
Olvidar instalar adaptadores para despliegue SSR
Pasar funciones como props a componentes server:defer (no serializables)
Acceder a Astro.session en páginas prerenderizadas (requiere renderizado bajo demanda)
Usar src/content/config.ts para proyectos nuevos (usar src/content.config.ts con cargadores)

Referencia Rápida

Estructura de Componente

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

<!-- Plantilla del Componente -->
<div>
  <h1>{title}</h1>
  <p>Count: {count}</p>
</div>

<style>
  /* Con ámbito por defecto */
  h1 { color: navy; }
</style>

Prioridad de Directivas

Sin directiva → HTML estático, cero JavaScript
server:defer → Renderizado diferido en el servidor (isla de servidor)
client:load → Hidratar inmediatamente al cargar la página
client:idle → Hidratar cuando el navegador esté inactivo
client:visible → Hidratar cuando el componente entre en el viewport
client:media → Hidratar cuando coincida la consulta de medios
client:only → Omitir SSR, renderizar solo en el cliente

Esquema de Colección de Contenido (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 };

Isla de Servidor

---
import UserAvatar from '../components/UserAvatar.astro';
---

<UserAvatar server:defer>
  <img slot="fallback" src="/generic-avatar.svg" alt="Cargando..." />
</UserAvatar>

Formato de Salida

Al implementar funcionalidades de Astro, proporciona:

Archivo de componente (.astro con frontmatter y plantilla)
Actualizaciones de configuración (astro.config.mjs si es necesario)
Esquema de colección de contenido (si se usan colecciones)
Tipos de TypeScript (para Props y datos)
Breve explicación de la estrategia de hidratación elegida

Tecnologías

Astro 5+/6+, Arquitectura de Islas, API de Capa de Contenido (cargadores glob/file, cargadores en vivo), Esquemas Zod, API de Transiciones de Vista, Islas de Servidor (server:defer), Sesiones, Acciones, Middleware, astro:env (variables de entorno con seguridad de tipos), Enrutamiento i18n, Adaptadores (Node, Vercel, Netlify, Cloudflare, Deno), Integraciones React/Vue/Svelte/Solid, Optimización de Imágenes, MDX, Markdoc, TypeScript, CSS con Ámbito, Tailwind CSS

PITT1/LandingPage-with-astro

¿Qué es LandingPage-with-astro?

Preguntar en tu IA favorita

Vista previa

Documentación