Configuración de Astro y las islas de React

Para iniciar un proyecto de Astro se utiliza npx create astro@latest, que ejecuta un asistente interactivo para elegir una plantilla, la configuración de TypeScript y el gestor de paquetes. Astro admite varios proyectos iniciales, como una plantilla vacía, una plantilla para blogs y plantillas para documentación.

Las integraciones de Astro añaden compatibilidad con frameworks a un proyecto. Al ejecutar npx astro add react, se instalan automáticamente @astrojs/react, react y react-dom, y se actualiza astro.config.mjs para incluir la integración de React. Toda la configuración se completa con un solo comando.

Un archivo .astro es el formato de componentes de Astro. Consta de una sección de frontmatter (JavaScript entre delimitadores ---) y una sección de plantilla. De forma predeterminada, un archivo de Astro genera HTML estático; no se envía JavaScript al navegador a menos que añada explícitamente una directiva de cliente.

Para importar un componente de React en un archivo de Astro se utiliza la sintaxis estándar de los módulos ES: import Counter from './Counter.jsx'. Sin una directiva de cliente, Astro renderiza el componente de React en el servidor como HTML estático y envía ese HTML al navegador; no se envía nada de JavaScript para el componente.

Al añadir client:visible a la etiqueta del componente en la plantilla de Astro, esta se convierte en una isla: <Counter client:visible />. Astro envía ahora el JavaScript de Counter, lo hidrata cuando entra en el área visible y lo vuelve interactivo. Sin la directiva, es HTML estático.

Los componentes de React utilizados como islas de Astro se escriben con React estándar: utilizan hooks, estado, efectos y cualquier biblioteca de React. El propio componente de React no contiene ninguna API específica de Astro. El límite de la isla se define en la plantilla de Astro, no dentro del código del componente.

Cada instancia de una isla es un árbol de React independiente. Dos islas Counter en la misma página no comparten el estado. Si necesita compartir estado, tiene tres opciones: combinarlas en una sola isla, utilizar parámetros de búsqueda de la URL para el estado serializable o utilizar una biblioteca de estado compartido como nanostores.

La biblioteca @nanostores/react proporciona átomos ligeros a los que cualquier isla puede suscribirse. Una isla escribe en un átomo de nano store y otra isla lo lee. Como los nano stores no dependen de ningún framework, este patrón también funciona entre islas de React y Vue en la misma página.

Las colecciones de contenido de Astro ofrecen una forma con comprobación de tipos para gestionar archivos Markdown y MDX. Defina el esquema de una colección con Zod, coloque los archivos Markdown en src/content/ y Astro generará funciones de consulta completamente tipadas. Este es el patrón estándar para publicaciones de blog, documentación y páginas de productos.

Al ejecutar astro build, se genera una carpeta dist/ con archivos HTML estáticos. Para cada página, Astro genera un archivo HTML con el contenido renderizado en el servidor y únicamente los paquetes de JavaScript necesarios para las islas de esa página. Las páginas sin islas no generan JavaScript.

El resultado estático se puede implementar en cualquier CDN (Netlify, Vercel, Cloudflare Pages) sin utilizar un servidor. Para necesidades de renderizado en el servidor (rutas dinámicas y endpoints de API), Astro admite adaptadores SSR para Node.js, Vercel Edge, Cloudflare Workers y Deno. Las islas funcionan de la misma forma en ambos modos.

¿Cuál es el cambio mínimo que debe hacer en un componente de React importado dentro de una plantilla de Astro para volverlo interactivo en el cliente?

Configure Astro con React mediante npx astro add react. Los archivos de Astro son estáticos de forma predeterminada; al añadir una directiva client: a la etiqueta de un componente de React, esta se convierte en una isla hidratada. Los componentes de React son React estándar y no utilizan API específicas de Astro. El estado está aislado por isla; nanostores permite la comunicación entre islas. La compilación genera HTML estático con únicamente el JavaScript necesario para las islas.