Islas Svelte en Astro: renderizar primero, hidratar solo lo necesario

Portátil con código iluminado en tonos azul y violeta
Fotografía de Daniil Komov · Unsplash (licencia gratuita). Referencia estética de programación web y componentes. · Ver imagen original

Un formulario puede estar dibujado correctamente antes de que se descargue su JavaScript. Tiene un campo de correo, un botón y etiquetas accesibles; sin embargo, todavía no responde a los eventos con el comportamiento que definimos en Svelte. Ese intervalo explica mejor las islas interactivas que la fórmula simplificada «Astro manda HTML y Svelte pone magia».

El objetivo no es usar una isla porque el componente sea pequeño: es decidir qué parte del documento necesita estado y eventos en el navegador. En este blog el artículo es contenido prerenderizado, mientras que el formulario es una isla Svelte. La estructura es suficiente para ilustrar las fronteras sin inventar tamaños de bundles ni afirmar que el formulario esté conectado a un servicio real de newsletters.

Arquitectura Astro con HTML inicial e hidratación de islas Svelte.
Diagrama editorial original. Los componentes interactivos cargan JavaScript de acuerdo con su directiva de hidratación.

Cuatro etapas que conviene no confundir

Para una isla hidratada hay cuatro momentos conceptualmente diferentes:

  1. Render del HTML. Astro construye la página; un componente Svelte puede producir marcado inicial en servidor o durante el build.
  2. Descarga. El navegador obtiene los módulos JavaScript que necesita la isla según su directiva client:*.
  3. Evaluación. El navegador ejecuta el código descargado; esto no es sinónimo de que el componente ya pueda responder completamente.
  4. Hidratación. El framework conecta el comportamiento del componente con el HTML y su estado inicial.

Un componente .astro no se hidrata por sí mismo con client:load. Las directivas se aplican a componentes de frameworks importados directamente desde un archivo .astro. Tampoco debe confundirse prerenderizado con sin JavaScript: la página puede ser estática en su origen e interactiva después de la hidratación. La documentación de islas y las directivas de Astro son las referencias primarias.

El costo de una isla no termina en el peso del script

El navegador debe transferir, analizar, evaluar y ejecutar la lógica del componente; también puede tener que cargar CSS y gestionar eventos. El costo depende de la dependencia real del framework, de módulos compartidos, del dispositivo, de la caché y de cómo se ha dividido el bundle. Decir «Svelte siempre pesa 4–8 KB» o «no tiene ningún runtime» no describe la salida de un build determinado y no constituye una medición.

Svelte compila componentes y puede producir JavaScript compacto, pero eso no elimina por completo sus dependencias de ejecución. La afirmación verificable para este proyecto es que Svelte administra la parte interactiva sin obligar a convertir todo el artículo en una aplicación cliente.

Ilustración conceptual de islas interactivas de Astro y Svelte: HTML estático, componentes y carga de JS.
Ilustración conceptual original: síntesis visual del tema del artículo, no captura ni prueba ejecutada.

Directivas: cuándo se activa la interactividad

Las cinco estrategias más importantes tienen una semántica distinta:

DirectivaCondición principalUso razonable
client:loadCarga e hidrata en cuanto arranca la páginaFormulario visible que debe estar disponible pronto
client:idleDifiere la carga a un período de inactividadWidget no crítico, bajo prioridad
client:visibleSe activa al entrar en la zona observadaInteracción que aparece más abajo en la lectura
client:media="(max-width: 48rem)"Espera a que coincida la media queryInterfaz solo necesaria en un rango de pantalla
client:only="svelte"Omite el render HTML de ese componente en servidorInterfaz dependiente de APIs del navegador durante el render

client:only no es una opción gratuita de rendimiento. Cuando el HTML inicial de una interfaz aporta significado, accesibilidad o descubrimiento, eliminar su render de servidor puede empeorar la experiencia; requiere una justificación clara y, si corresponde, un fallback.

Una directiva tampoco sustituye condiciones de negocio: que el formulario se hidrate temprano no hace que el backend persista datos. La elección debe responder a un requisito funcional, no a una tabla de «la más rápida».

Un caso real del repositorio: el formulario de suscripción

El proyecto declara Astro 4 (^4.16.18), Svelte 4 (^4.2.19) y @astrojs/svelte 5.x. El formulario vive en src/components/SubscribeForm.svelte, y la página del artículo lo utiliza así:

---
import SubscribeForm from '../../components/SubscribeForm.svelte';
---

<SubscribeForm variant="plain" client:load />

En Svelte 4 se declaran variables reactivas ordinarias; los eventos se escuchan con on:submit y on:input, y bind:value conecta el estado del input. El siguiente fragmento abrevia el patrón del componente real para aislar el control de estado; no reemplaza su gestión de errores ni el HTML accesible del proyecto:

<script lang="ts">
  let email = '';
  let status: 'idle' | 'loading' | 'success' | 'error' = 'idle';

  async function submit(event: Event) {
    event.preventDefault();
    if (status === 'loading') return;
    status = 'loading';
    try {
      const response = await fetch('/api/subscribe', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email: email.trim() }),
      });
      status = response.ok ? 'success' : 'error';
    } catch {
      status = 'error';
    }
  }
</script>

<form on:submit={submit}>
  <label for="signup-email">Correo electrónico</label>
  <input id="signup-email" type="email" required bind:value={email} />
  <button type="submit" disabled={status === 'loading'}>
    {status === 'loading' ? 'Procesando…' : 'Enviar'}
  </button>
</form>

Un código de respuesta HTTP satisfactorio no demuestra que se haya creado una suscripción. El endpoint actual, src/pages/api/subscribe.ts, valida el formato del correo y responde con un resultado simulado; no envía correos ni persiste direcciones. El componente real, además, informa de ello en la interfaz y utiliza aria-live, estados de error y controles de reinicio. Es importante conservar esa distinción para no convertir un mock de integración en una funcionalidad inexistente.

¿Por qué client:load en vez de client:visible?

La implementación actual usa client:load tanto en el artículo como en superficies donde se invita a enviar el formulario. Con client:visible podría diferirse JavaScript si el widget está muy lejos del primer viewport, pero un usuario que llega rápidamente a él podría encontrar un breve intervalo sin respuesta interactiva. Esa es una hipótesis de diseño para medir con instrumentación y pruebas, no una razón universal para elegir una directiva.

La decisión correcta requiere observar ubicación del widget, tiempos de interacción, HTML visible sin JS, estado de carga y errores reales. Una prueba en navegador debería confirmar al menos que el control no provoca envíos duplicados y que informa fallos de conexión de forma comprensible.

Svelte 4 no es Svelte 5

La documentación actual de la integración se centra en Svelte 5 y aconseja utilizar @astrojs/svelte@5 para Svelte 3/4. Este repositorio ya está en esa línea de integración. Cambiar ejemplos del blog a $props(), $state() y onclick como si estuvieran disponibles en su configuración actual sería mezclar una migración futura con el caso estudiado.

ResponsabilidadSvelte 4 del proyectoEn ejemplos de Svelte 5
Propsexport let variant = 'plain'let { variant } = $props()
Estadolet status = 'idle'let status = $state('idle')
Eventos de componente/DOMon:submit={submit}onsubmit={submit}
EfectosReactividad legacy ($: cuando corresponde)$effect() para efectos cliente

La tabla sirve para leer documentación sin copiar sintaxis incompatible. No propone migrar el proyecto a Svelte 5. Antes de hacerlo hay que revisar versiones de Astro, integración, componentes y dependencias, y ejecutar build y pruebas.

La frontera de los datos: props y comunicación entre islas

Una página Astro puede pasar a una isla los datos iniciales que necesita renderizar. Esas props deben poder serializarse de acuerdo con las reglas de Astro. No se debe intentar enviar una función con estado del servidor, una conexión de base de datos o un objeto de infraestructura como si fuera una prop convencional disponible en el navegador.

Para interfaces pequeñas, una prop inicial y un evento local suelen bastar. Cuando dos islas lejanas necesitan coordinarse, hay varias opciones, con costes diferentes:

  • URL y query params para estado navegable y compartible, como filtros y búsquedas.
  • Eventos del DOM para una comunicación acotada entre componentes de una misma página; requieren decidir quién escucha y limpia esos listeners.
  • Estado persistido y servidor para información que debe sobrevivir a la navegación, validarse o protegerse mediante permisos.
  • Store cliente compartido cuando existe una necesidad sostenida de sincronizar varias islas; añade complejidad y acoplamiento.

Si la página acaba necesitando gran cantidad de estado cliente coordinado y navegación interna, evaluar una arquitectura de aplicación puede ser mejor que forzar docenas de islas independientes. La isla es una frontera útil, no una prohibición de usar una SPA cuando la necesidad lo justifica.

Formularios, accesibilidad y seguridad

El ejemplo muestra que el cliente ejecuta fetch, pero la autoridad sobre la petición la tiene el servidor. La validación de type="email" y el estado de Svelte solo mejoran la experiencia: no pueden reemplazar validación de backend, límites de abuso, protección de datos, decisiones de consentimiento y manejo seguro de errores.

La implementación del blog valida una forma mínima del email; todavía no tiene integración con un proveedor. Convertirlo en un formulario real requeriría definir persistencia, política de datos, tratamiento de peticiones repetidas y garantías frente a errores. Tampoco es un ejemplo progressive enhancement que funcione automáticamente sin JavaScript: el formulario actual intercepta el submit y el endpoint espera JSON, así que convendría diseñar un flujo HTML alternativo si ese fuera un requisito.

La UI también importa. El input debe conservar label, estado de espera, errores anunciables y un botón deshabilitado mientras procesa. Estas propiedades no son exclusivas de Svelte: reflejan contratos de un formulario accesible que seguirían existiendo con React, Vue o HTML tradicional.

Cómo verificar el resultado sin inventar un benchmark

Un control técnico útil después de editar una isla es comparar la salida prerenderizada y la interacción en el navegador:

  1. Ejecutar bun run build y bun run test con el lockfile del proyecto.
  2. Inspeccionar el HTML inicial de la ruta del artículo: contenido disponible y markup previsto del formulario.
  3. En navegador, enviar email inválido, un intento válido y simular error de red; comprobar estados y anuncios accesibles.
  4. Inspeccionar Network/Performance para separar descarga de código y tiempo hasta interacción.
  5. Medir en un entorno documentado antes de afirmar ahorro de KB, mejoras de INP o cambios de LCP.

No se ejecutó esta batería como parte de la redacción del artículo. El fragmento Svelte anterior es ilustrativo y el código verdadero de referencia es el componente versionado en el repositorio.

Conclusión: hidratar por necesidad, no por costumbre

Astro decide qué estructura puede entregarse como HTML; Svelte aporta interactividad donde el documento la necesita. La frontera técnica más importante no está en la marca del framework, sino en el momento en que el navegador descarga código y asume estado. Mantener esa frontera explícita facilita diagnosticar problemas de rendimiento, accesibilidad y mantenimiento.

Si quieres comprender cómo se prepara el contenido antes de llegar a una isla, consulta Por qué elegí Astro. El artículo sobre formularios en SvelteKit desarrolla otra arquitectura posible para gestionar POST, pero no debe confundirse su modelo de form actions con el endpoint JSON de Astro de este proyecto.

Referencias: Astro Islands, directivas de Astro, integración Svelte y documentación de Svelte 5 sobre estado (esta última, solo para contraste de versiones).