Reglas de Arquitectura de Astro v6 (Modo Estricto)

# Reglas de Arquitectura de Astro v6 (Modo Estricto) ## 1. Filosofía Central - Sigue el principio de Astro de "HTML primero / cero JavaScript por defecto": - Todo es HTML estático a menos que la interactividad sea explícitamente requerida. - JavaScript es un costo, solo agrégalo cuando crea valor real para el usuario. - Siempre piensa en "Arquitectura de Islas": - La página es HTML estático - Las partes interactivas son islas aisladas - Nunca trates la página completa como una aplicación - Antes de escribir cualquier JavaScript, pregúntate siempre: "¿Se puede resolver esto con HTML + CSS o lógica del lado del servidor?" ## 2. Modelo de Componentes - Usa componentes `.astro` para: - Diseño - Composición - UI estática - Obtención de datos - Lógica del lado del servidor (frontmatter) - Componentes `.astro`: - Se ejecutan en tiempo de compilación o del lado del servidor - NO envían JavaScript por defecto - Deben permanecer agnósticos al framework - NUNCA uses hooks de React/Vue/Svelte dentro de `.astro` ## 3. Islas (Componentes Interactivos) - Solo usa componentes de frameworks (React, Vue, Svelte, etc.) para interactividad. - Trata cada componente interactivo como una isla aislada: - Independiente - Autocontenido - Alcance mínimo - NUNCA: - Hidrates páginas o diseños completos - Envuelvas árboles grandes en una sola isla - Crear muchas islas pequeñas en bucles innecesariamente - Prefiere: - Renderizado de listas estáticas - Hidratar solo la unidad interactiva mínima ## 4. Estrategia de Hidratación (Crítico) - Siempre define explícitamente la hidratación usando directivas `client:*`. - Elige la prioridad MÁS BAJA posible: - `client:load` -> Solo para interactividad crítica en la parte superior de la página - `client:idle` -> Para UI secundaria después de la carga de la página - `client:visible` -> Para componentes pesados o debajo del pliegue - `client:media` -> Para UI responsiva / condicional - `client:only` -> SOLO cuando SSR falla (window, localStorage, etc.) - Regla por defecto: - Nunca uses `client:load` por defecto - Prefiere `client:visible` o `client:idle` - La hidratación es un presupuesto de rendimiento: - Cada isla agrega JavaScript - Mantén el JavaScript total mínimo ## 5. Lógica del Servidor vs. del Cliente - Prefiere la lógica del lado del servidor (dentro del frontmatter de `.astro`) para: - Obtención de datos - Transformaciones - Filtrado / ordenamiento - Valores derivados - Solo usa estado del lado del cliente cuando: - La interacción del usuario lo requiere - Se necesitan actualizaciones en tiempo real - Evita: - Duplicar lógica en el cliente - Mover lógica del servidor a las islas ## 6. Gestión de Estado - Evita el estado del cliente a menos que sea estrictamente necesario. - Si es necesario: - Limita el estado dentro de la isla solamente - NO crees estado global de la aplicación a menos que sea requerido - Para estado entre islas: - Usa almacenes compartidos ligeros (por ejemplo, nano stores) - Evita sistemas de estado global pesados por defecto ## 7. Restricciones de Rendimiento (Reglas Estrictas) - Minimiza el JavaScript enviado al cliente: - Astro solo carga JavaScript para componentes hidratados - Prefiere: - Renderizado estático - Hidratación parcial - Hidratación diferida - Evita: - Hidratar listas grandes - Islas repetidas en bucles - Uso excesivo de `client:load` - Cada isla: - Tiene su propio bundle - Se carga de forma independiente - Debe permanecer pequeña y enfocada ## 8. Estructura de Archivos y Proyecto - `/pages` - Puntos de entrada (SSG/SSR), sin lógica de cliente - `/components` - UI compartida, las islas viven aquí - `/layouts` - Solo envoltorios estáticos - `/content` - Datos de Markdown / CMS - Mantén los archivos `.astro` enfocados en la composición, no en el comportamiento ## 9. Anti-Patrones (Estrictamente Prohibidos) - Usar hooks en `.astro` - Convertir Astro en arquitectura SPA - Hidratar el diseño o la página completa - Usar `client:load` en todas partes - Mapear listas en componentes hidratados - Usar JavaScript del cliente para problemas estáticos - Reemplazar lógica del servidor con lógica del cliente ## 10. Patrones Preferidos - Renderizado estático primero - Islas mínimas y aisladas - Hidratación diferida (`visible`, `idle`) - Computación del lado del servidor - HTML + CSS antes de JavaScript - Mejora progresiva ## 11. Marco de Decisión (MUY IMPORTANTE) Para cada característica: 1. ¿Puede ser HTML estático? -> SÍ -> Usa `.astro` 2. ¿Requiere interacción? -> NO -> Mantente estático 3. ¿Requiere JavaScript? -> SÍ -> Crea una isla 4. ¿Cuándo debería cargar? -> Elige la prioridad MÁS BAJA de `client:*` ## 12. Modelo Mental (No Negociable) - Astro NO es: - Next.js - Framework SPA - Sistema centrado en React - Astro ES: - Renderizador estático primero - Sistema de hidratación parcial - Arquitectura centrada en el rendimiento - Piensa: "Envía HTML + espolvorea JavaScript"