Problemas Comunes del Renderizado del Lado del Servidor con Runes en Svelte 5

El Paradigma de la Aplicación Universal

El renderizado del lado del servidor representa un cambio de paradigma en cómo pensamos sobre la arquitectura de aplicaciones web. A diferencia de los primeros días de las aplicaciones de página única donde JavaScript era el único responsable de renderizar contenido en el navegador, los frameworks modernos como SvelteKit adoptan un enfoque "universal" donde el código de tu aplicación se ejecuta en múltiples entornos. Esta decisión arquitectónica trae beneficios enormes — cargas iniciales de página más rápidas, mejor SEO, mayor accesibilidad y degradación elegante cuando JavaScript falla — pero también introduce una categoría de desafíos que muchos desarrolladores encuentran confusos y frustrantes.

Cuando Svelte 5 introdujo los runes como el nuevo primitivo reactivo, cambió fundamentalmente la manera en que los desarrolladores expresan la reactividad en sus aplicaciones. Los runes $state, $derived y $effect proporcionan un modelo de reactividad más explícito y predecible en comparación con las declaraciones reactivas implícitas de Svelte 4. Sin embargo, este nuevo modelo interactúa con el renderizado del lado del servidor de maneras que requieren una comprensión cuidadosa. Un rune que funciona perfectamente en un contexto exclusivamente de cliente podría provocar bugs sutiles, desajustes de hidratación o fallas directas cuando tu componente se ejecuta en el servidor.

Este tutorial tiene como objetivo construir un modelo mental integral para entender SSR con los runes de Svelte 5. En lugar de simplemente proporcionar fragmentos de código para copiar, exploraremos los principios subyacentes que rigen cómo el código se ejecuta en diferentes entornos, por qué ciertos patrones causan problemas y cómo pensar en el diseño de componentes de una manera que naturalmente evite los problemas de SSR. Al final de este análisis profundo, no solo tendrás soluciones a problemas comunes, sino el marco conceptual para razonar sobre nuevas situaciones que encuentres.

Entendiendo la Naturaleza Fundamental de las Aplicaciones Universales

Para comprender verdaderamente los problemas de SSR, primero debemos entender qué significa que una aplicación sea "universal". Este término describe aplicaciones donde el mismo código base se ejecuta en entornos fundamentalmente diferentes: el servidor (típicamente Node.js, pero potencialmente Deno, Bun, o runtimes de borde como Cloudflare Workers) y el navegador. Estos entornos comparten JavaScript como lenguaje, pero difieren drásticamente en sus APIs disponibles, modelos de ejecución y propósitos.

Considera qué sucede cuando un usuario navega a tu aplicación SvelteKit por primera vez. Su navegador envía una solicitud HTTP a tu servidor. El servidor recibe esta solicitud y necesita responder con HTML que el navegador pueda mostrar. En una aplicación tradicional renderizada en el servidor (piensa en PHP o Ruby on Rails), el servidor usaría plantillas para generar este HTML directamente. En una SPA de lado del cliente, el servidor devolvería una capa mínima de HTML, y JavaScript construiría toda la página en el navegador.

SvelteKit adopta un enfoque híbrido. Cuando el servidor recibe la solicitud, ejecuta tus componentes Svelte — ejecutando el código JavaScript que escribiste — para producir el HTML inicial. Esto significa que el bloque <script> de tu componente se ejecuta en el servidor, tus declaraciones reactivas son evaluadas, y Svelte renderiza el marcado resultante en una cadena HTML. Este HTML se envía al navegador, donde el usuario ve inmediatamente contenido significativo.

Pero la historia no termina ahí. El navegador también recibe tu bundle de JavaScript. Una vez que este JavaScript se carga y ejecuta, Svelte realiza un proceso llamado "hidratación" donde toma el HTML renderizado en el servidor y lo hace interactivo. Durante la hidratación, el código de tu componente se ejecuta nuevamente — esta vez en el navegador — y Svelte adjunta manejadores de eventos, establece suscripciones reactivas y prepara la aplicación para la interacción del usuario.

Esta ejecución dual es la fuente de todos los problemas de SSR que discutiremos. Tu código se ejecuta dos veces: una vez en el servidor para generar HTML, y una vez en el cliente para habilitar la interactividad. Entender esta realidad fundamental es la clave para evitar problemas.

¿Por Qué Existe Esta Arquitectura?

Antes de profundizar en los detalles técnicos, vale la pena entender por qué SvelteKit (y frameworks como Next.js, Nuxt y Remix) eligieron esta arquitectura. Los beneficios son lo suficientemente sustanciales como para justificar la complejidad adicional.

El rendimiento y la velocidad percibida representan la motivación principal. Cuando un usuario solicita una página, quiere ver contenido lo más rápido posible. Con el renderizado del lado del cliente, el navegador debe descargar la capa HTML, luego descargar el bundle de JavaScript, luego ejecutar el JavaScript para renderizar el contenido. Solo después de completar todos estos pasos el usuario ve algo significativo. Con SSR, el servidor envía HTML completo de inmediato. El usuario ve el contenido mientras JavaScript se descarga en segundo plano. Esto mejora drásticamente el rendimiento percibido, especialmente en conexiones más lentas o dispositivos menos potentes.

La optimización para motores de búsqueda proporciona otra razón convincente. Si bien los motores de búsqueda modernos pueden ejecutar JavaScript e indexar contenido renderizado en el cliente, SSR asegura que los crawlers vean el contenido completo de inmediato. Esto elimina la incertidumbre sobre cómo los motores de búsqueda interpretarán tus páginas y puede mejorar tu posicionamiento en búsquedas.

La accesibilidad y la mejora progresiva se benefician significativamente del SSR. Los usuarios que navegan con JavaScript deshabilitado (ya sea por elección o debido a firewalls corporativos) aún pueden acceder a tu contenido. Los lectores de pantalla reciben el marcado completo de inmediato en lugar de esperar la ejecución de JavaScript. La aplicación se degrada elegantemente cuando algo sale mal.

El uso compartido en redes sociales depende de SSR para generar vistas previas de enlaces. Cuando alguien comparte un enlace a tu sitio en Twitter o Facebook, esas plataformas obtienen el HTML y extraen metadatos. No ejecutan JavaScript, por lo que el contenido renderizado en el cliente no aparecería en las vistas previas.

Estos beneficios explican por qué la industria ha migrado en gran medida hacia SSR para aplicaciones en producción. Entender este contexto ayuda a enmarcar los desafíos que abordaremos: la complejidad de SSR es el precio que pagamos por estos beneficios sustanciales.

Los Dos Entornos: Una Comparación Detallada

Examinemos en detalle las diferencias entre los entornos del servidor y del navegador, ya que estas diferencias son la causa raíz de la mayoría de los problemas de SSR.

El entorno del servidor se ejecuta en Node.js (o un runtime similar). Este entorno no tiene concepto de pantalla visual, interacción del usuario o APIs del navegador. No existe el objeto window, ni document, ni localStorage, ni navigator, ni IntersectionObserver, ni ResizeObserver. El servidor no conoce el tamaño de pantalla del usuario, la preferencia de esquema de color, la zona horaria o el idioma. No puede reproducir audio, renderizar en canvas ni acceder al portapapeles. El trabajo del servidor es procesar una solicitud y producir una respuesta lo más rápido posible — idealmente en milisegundos.

La ejecución del servidor también es fundamentalmente diferente en su ciclo de vida. Cuando el servidor renderiza tu componente, ejecuta tu código de manera síncrona, produce HTML y descarta todo el estado. No hay un proceso continuo que observe los cambios. El servidor renderiza una vez y continúa. Si 1000 usuarios solicitan la misma página, el servidor la renderiza 1000 veces (a menos que implementes caché), con cada renderizado siendo independiente y sin estado.

El entorno del navegador está lleno de APIs pero restringido de maneras diferentes. Tiene acceso a todas las APIs de la plataforma web — manipulación del DOM, almacenamiento, sensores del dispositivo, reproducción de medios — pero se ejecuta en un sandbox con restricciones de seguridad. El navegador no puede acceder al sistema de archivos, ejecutar comandos de shell ni conectarse directamente a bases de datos. Se ejecuta en un event loop que responde a interacciones del usuario, respuestas de red y callbacks de temporizadores.

La ejecución del navegador también es persistente dentro de una sesión. Una vez que tu componente se monta, permanece activo hasta que el usuario navega o cierra la pestaña. El estado persiste a través de las interacciones. Los efectos se ejecutan y se vuelven a ejecutar en respuesta a cambios de estado. El componente existe en el tiempo, respondiendo a un flujo continuo de eventos.

La idea crucial es que los entornos del servidor y del navegador comparten casi nada excepto el lenguaje JavaScript en sí. Cuando escribes código que asume que existen APIs del navegador, ese código fallará en el servidor. Cuando escribes código que asume estado persistente, ese código no funcionará correctamente con el modelo de renderizado único de SSR. El SSR exitoso requiere escribir código que funcione correctamente en ambos entornos — o manejar explícitamente las diferencias.

La Línea de Tiempo de SSR: Un Análisis Momento a Momento

Entender exactamente cuándo se ejecuta el código es esencial para evitar problemas de SSR. Sigamos el ciclo de vida completo de una solicitud de página, examinando qué sucede en cada etapa.

Fase 1: El Servidor Recibe una Solicitud

Todo comienza con una solicitud HTTP. Un usuario escribe una URL, hace clic en un enlace o envía un formulario. Su navegador envía una solicitud a tu servidor. El código del lado del servidor de SvelteKit recibe esta solicitud y comienza a procesarla.

Durante esta fase, SvelteKit ejecuta tus funciones load de +page.server.js y +page.js (si existen). Estas funciones pueden acceder a recursos del lado del servidor como bases de datos, realizar llamadas API autenticadas y preparar datos para tus componentes. Los datos retornados por las funciones load quedan disponibles como props para tus componentes de página.

También es aquí cuando se leen las cookies, se validan las sesiones de usuario y se ejecuta cualquier lógica del lado del servidor. De manera crucial, esto ocurre antes de que se ejecute cualquier código de componente. Para cuando tus componentes Svelte se ejecutan, las funciones load ya han completado.

Fase 2: Ejecución de Componentes en el Servidor

Con los datos cargados, SvelteKit comienza a renderizar tu árbol de componentes. Empezando desde el layout raíz y trabajando hacia abajo a través de los layouts anidados hasta tu componente de página, Svelte ejecuta el bloque <script> de cada componente.

Aquí es donde las cosas se vuelven interesantes para los runes. Cuando el servidor ejecuta tu componente:

Las declaraciones $state se ejecutan e inicializan. El valor inicial que proporcionas se convierte en el valor del estado. Si escribes let count = $state(0), la variable count tiene el valor 0. Cualquier modificación síncrona posterior a este estado se captura — si inmediatamente escribes count = 10, el estado se convierte en 10.

Las declaraciones $derived calculan sus valores. Svelte evalúa la expresión de derivación usando los valores de estado actuales. Si escribes let doubled = $derived(count * 2), y count es 10, entonces doubled se convierte en 20.

Los bloques $effect son completamente ignorados. Esta es quizás la regla más importante a internalizar. Los efectos no se ejecutan en el servidor. Punto. El servidor omite los bloques $effect por completo. Esto tiene sentido cuando lo piensas: los efectos están diseñados para efectos secundarios que responden a cambios de estado a lo largo del tiempo, pero el servidor renderiza una vez y descarta el resultado. No hay "a lo largo del tiempo" en el servidor.

$props recibe valores de los componentes padre. Los props funcionan de manera idéntica en el servidor y el cliente — son simplemente valores pasados de padre a hijo.

Los callbacks de onMount no se llaman. Al igual que los efectos, onMount solo se ejecuta en el navegador. El callback se registra pero no se ejecuta.

Los callbacks de onDestroy se llaman después de que el renderizado se completa. Este es el único hook de ciclo de vida que se ejecuta en el servidor, permitiendo la limpieza de cualquier recurso asignado durante el paso de renderizado.

Después de que todos los componentes se han ejecutado, Svelte serializa el árbol de componentes resultante en una cadena HTML. Este HTML representa el estado inicial completo de tu página.

Fase 3: Entrega del HTML al Navegador

El servidor envía la respuesta HTML al navegador. Esta respuesta incluye el HTML renderizado, más etiquetas <script> que cargarán tu bundle de JavaScript, más cualquier dato serializado que el cliente necesite para la hidratación.

En este momento, el usuario ve tu página. El contenido es visible y legible. Los enlaces están presentes (aunque hacer clic en ellos causaría recargas completas de página sin JavaScript). Los formularios existen (y funcionarían a través del envío de formularios tradicional sin JavaScript). La página es utilizable, aunque no completamente interactiva.

Este es el beneficio de SSR: el contenido significativo aparece antes de que JavaScript haya comenzado a cargar. En conexiones lentas, esto podría ahorrar segundos de espera. En conexiones rápidas, sigue siendo perceptiblemente más rápido que esperar a que JavaScript renderice todo.

Fase 4: Carga y Análisis de JavaScript

Mientras el usuario ve el HTML, su navegador descarga tu bundle de JavaScript en segundo plano. Dependiendo del tamaño del bundle y la velocidad de conexión, esto puede tomar desde milisegundos hasta varios segundos.

Una vez descargado, el navegador analiza y ejecuta el JavaScript. Esto es computacionalmente costoso, especialmente en dispositivos móviles. El hilo principal está ocupado durante este tiempo, lo que puede hacer que la página se sienta poco responsiva si el bundle es grande.

Fase 5: Hidratación

La hidratación es donde ocurre la magia — y donde los bugs de SSR suelen manifestarse. Durante la hidratación, Svelte "se adjunta" al DOM existente en lugar de crear nuevos elementos.

El proceso de hidratación funciona aproximadamente así:

Svelte crea su estructura interna de árbol de componentes, reflejando lo que se creó en el servidor.
Para cada componente, Svelte ejecuta el bloque <script> nuevamente — sí, tu código se ejecuta por segunda vez.
Svelte recorre el DOM existente, haciendo coincidir los elementos con su representación interna.
Los manejadores de eventos se adjuntan a los elementos del DOM existentes.
Se establecen suscripciones reactivas para que la UI pueda responder a cambios de estado.
Los bloques $effect se ejecutan por primera vez.
Se llaman los callbacks de onMount.

El punto crítico es el paso 3: Svelte espera que el DOM existente coincida con lo que habría renderizado. Si el servidor renderizó <p>Hello</p> pero el código del cliente renderizaría <p>World</p>, Svelte detecta este desajuste. En desarrollo, verás advertencias en la consola. En producción, Svelte intenta reconciliar la diferencia, pero esto puede causar fallas visuales, manejadores de eventos rotos o comportamiento incorrecto.

Por eso ocurren los desajustes de hidratación: cuando el servidor y el cliente producen resultados diferentes. Entender las causas de estos desajustes — y cómo evitarlos — es esencial para el éxito con SSR.

Fase 6: Navegación del Lado del Cliente

Después de que la hidratación se completa, tu aplicación es completamente interactiva. El usuario puede hacer clic en botones, llenar formularios y activar cambios de estado. El sistema de reactividad de Svelte responde a estos cambios, actualizando el DOM según sea necesario.

Cuando el usuario navega a una página diferente dentro de tu aplicación (haciendo clic en un enlace interno), SvelteKit intercepta la navegación y la maneja del lado del cliente. No se realiza una nueva solicitud al servidor para el HTML. En cambio, SvelteKit carga el módulo JavaScript de la nueva página (si no está ya en caché), obtiene datos de las funciones load y monta el nuevo componente de página.

Esta navegación del lado del cliente no involucra SSR. Los componentes se montan nuevos en el navegador. Es por eso que algunos bugs de SSR solo aparecen en la carga inicial de la página pero no en la navegación posterior — la navegación del lado del cliente omite el servidor por completo.

Análisis Profundo: Cómo Se Comporta Cada Rune Durante SSR

Ahora que entendemos la línea de tiempo, examinemos en detalle el comportamiento de cada rune. Entender estos comportamientos te ayudará a anticipar problemas antes de que ocurran.

El Rune `$state`: Inicialización de Estado Reactivo

El rune $state crea estado reactivo que activa actualizaciones de la UI cuando se modifica. A primera vista, parece sencillo: declaras una variable con un valor inicial, y esa variable se vuelve reactiva.

<script>
	let count = $state(0)
	let user = $state({ name: 'Anonymous', loggedIn: false })
	let items = $state(['apple', 'banana', 'cherry'])
</script>

Durante SSR, estas declaraciones funcionan exactamente como esperarías. Las variables se inicializan con los valores proporcionados. Si las modificas de manera síncrona durante la ejecución del script, esas modificaciones tienen efecto:

<script>
	let count = $state(0)

	// This synchronous modification happens during SSR
	count = 10

	// The HTML will show 10, not 0
</script>

<p>Count: {count}</p>

La complejidad surge cuando intentas inicializar el estado desde fuentes que no existen en el servidor. Considera este código aparentemente razonable:

<script>
	// DANGEROUS: localStorage doesn't exist on the server!
	let savedTheme = $state(localStorage.getItem('theme') || 'light')
</script>

Este código fallará durante SSR con un error de "localStorage is not defined". El servidor no tiene localStorage — es una API exclusiva del navegador. Lo mismo aplica a cualquier inicialización que dependa de APIs del navegador:

<script>
	// DANGEROUS: window doesn't exist on the server!
	let windowWidth = $state(window.innerWidth)

	// DANGEROUS: document doesn't exist on the server!
	let cookies = $state(document.cookie)

	// DANGEROUS: navigator doesn't exist on the server!
	let userAgent = $state(navigator.userAgent)
</script>

La solución implica proporcionar valores predeterminados seguros y diferir la inicialización específica del navegador a $effect, lo cual exploraremos pronto.

Otro problema sutil involucra la reactividad profunda. Cuando usas $state con un objeto o array, Svelte crea un proxy profundamente reactivo. Esto funciona de manera idéntica en el servidor y el cliente, pero el comportamiento del proxy tiene implicaciones para la serialización:

<script>
	let todos = $state([
		{ id: 1, text: 'Learn SSR', done: false },
		{ id: 2, text: 'Avoid gotchas', done: false }
	])

	// This is a deeply reactive proxy
	// Modifications to nested properties trigger updates
	todos[0].done = true // This works reactively
</script>

La naturaleza del proxy significa que no puedes serializar directamente los valores de $state con JSON.stringify — necesitas usar $state.snapshot() primero. Esto típicamente no es un problema durante SSR normal, pero importa si estás serializando estado para depuración o transferencia de datos.

El Rune `$derived`: Valores Computados y Sus Dependencias

El estado derivado representa valores computados que se actualizan automáticamente cuando cambian sus dependencias. Conceptualmente, las derivaciones son funciones puras de otro estado:

<script>
	let firstName = $state('John')
	let lastName = $state('Doe')

	// This derivation depends on firstName and lastName
	let fullName = $derived(`${firstName} ${lastName}`)

	// Complex derivations use $derived.by
	let initials = $derived.by(() => {
		return `${firstName[0]}${lastName[0]}`
	})
</script>

Las derivaciones funcionan perfectamente durante SSR porque son cómputos puros sin efectos secundarios. El servidor evalúa la expresión de derivación usando los valores de estado actuales y renderiza el resultado. El cliente la vuelve a evaluar durante la hidratación y (asumiendo las mismas entradas) produce el mismo resultado.

El problema con las derivaciones ocurre cuando dependen de estado que difiere entre el servidor y el cliente. Considera este ejemplo:

<script>
	import { browser } from '$app/environment'

	let screenWidth = $state(browser ? window.innerWidth : 1024)
	let isMobile = $derived(screenWidth < 768)
</script>

<nav class:mobile={isMobile}>
	<!-- Navigation content -->
</nav>

Durante SSR, screenWidth es 1024 (nuestro valor de respaldo), por lo que isMobile es false. El servidor renderiza <nav> sin la clase mobile. Pero si el usuario tiene un teléfono con pantalla de 600px, la hidratación establece screenWidth en 600, haciendo que isMobile se convierta en true. El cliente espera <nav class="mobile">, pero el DOM tiene <nav>. ¡Desajuste de hidratación!

La solución es asegurar que las derivaciones produzcan valores consistentes entre el servidor y el cliente durante el renderizado inicial. Exploraremos patrones para esto en secciones posteriores.

Otra consideración es que las derivaciones no pueden contener efectos secundarios. Svelte lo hace cumplir — no puedes modificar estado dentro de una expresión $derived:

<script>
	let count = $state(0)
	let log = $state([])

	// ERROR: Cannot modify state inside $derived
	let doubled = $derived(() => {
		log.push(count) // This is forbidden!
		return count * 2
	})
</script>

Esta restricción existe porque las derivaciones podrían evaluarse múltiples veces (para el seguimiento de dependencias) o podrían no evaluarse en absoluto (si nada las lee). Los efectos secundarios dentro de las derivaciones tendrían un comportamiento impredecible. Esta restricción aplica por igual durante SSR y en el navegador.

El Rune `$effect`: Tu Puerto Seguro para Código del Navegador

El rune $effect crea efectos secundarios que se ejecutan en respuesta a cambios de estado. A diferencia de $state y $derived, los efectos son fundamentalmente exclusivos del cliente. Nunca se ejecutan en el servidor.

Este comportamiento es intencional y crucial de entender. Los efectos están diseñados para tareas como:

Interactuar con APIs del navegador (localStorage, mediciones del DOM, etc.)
Suscribirse a fuentes de datos externas
Realizar registro o análisis
Integrarse con bibliotecas de terceros que requieren contexto del navegador
Gestionar temporizadores e intervalos
Manejar el foco y las interacciones del teclado

Ninguna de estas tiene sentido en un contexto de servidor. El servidor no tiene DOM que medir, no tiene localStorage que leer, no tiene navegador con el que interactuar. Al omitir los efectos durante SSR, Svelte mantiene el renderizado del servidor rápido y evita fallas por APIs del navegador faltantes.

<script>
	let mousePosition = $state({ x: 0, y: 0 })

	$effect(() => {
		// This entire block is ignored during SSR
		// It only runs after hydration in the browser

		function handleMouseMove(event) {
			mousePosition = { x: event.clientX, y: event.clientY }
		}

		window.addEventListener('mousemove', handleMouseMove)

		// Cleanup function runs when effect re-runs or component unmounts
		return () => {
			window.removeEventListener('mousemove', handleMouseMove)
		}
	})
</script>

<p>Mouse: ({mousePosition.x}, {mousePosition.y})</p>

El patrón mostrado arriba es fundamental para las interacciones con el navegador seguras para SSR. Observa que mousePosition tiene un valor predeterminado seguro para SSR de { x: 0, y: 0 }. El servidor renderiza este valor predeterminado. Después de la hidratación, el efecto se ejecuta y comienza a actualizar mousePosition con las coordenadas reales del mouse.

Los efectos también manejan las dependencias reactivas automáticamente. Svelte rastrea qué valores de estado lees dentro del efecto y vuelve a ejecutar el efecto cuando esos valores cambian:

<script>
	let userId = $state(null)
	let userData = $state(null)

	$effect(() => {
		// This effect re-runs whenever userId changes
		if (!userId) {
			userData = null
			return
		}

		// Fetch user data from API
		fetch(`/api/users/${userId}`)
			.then((res) => res.json())
			.then((data) => {
				userData = data
			})
	})
</script>

Entender las dependencias de un efecto es importante porque determina cuándo los efectos se vuelven a ejecutar. Los valores leídos sincrónicamente dentro del cuerpo del efecto (antes de cualquier await o dentro de setTimeout) se convierten en dependencias. Los valores leídos de forma asincrónica (después de await o dentro de callbacks) no se convierten en dependencias:

<script>
	let searchTerm = $state('')
	let results = $state([])
	let sortOrder = $state('asc')

	$effect(() => {
		// searchTerm is a dependency (read synchronously)
		const term = searchTerm

		if (!term) {
			results = []
			return
		}

		// Perform search
		fetch(`/api/search?q=${encodeURIComponent(term)}`)
			.then((res) => res.json())
			.then((data) => {
				// sortOrder is NOT a dependency (read asynchronously)
				// Changing sortOrder won't trigger a new search
				results = data.sort((a, b) => (sortOrder === 'asc' ? a.rank - b.rank : b.rank - a.rank))
			})
	})
</script>

Este seguimiento de dependencias funciona de la misma manera después de la hidratación que en un componente solo de cliente. La única diferencia es que la ejecución inicial del efecto ocurre después de la hidratación en lugar de después de la inicialización del componente.

La Runa `$effect.pre`: Efectos Secundarios Antes de la Actualización del DOM

La runa $effect.pre es una variante especializada que se ejecuta antes de las actualizaciones del DOM en lugar de después. Al igual que los efectos regulares, los pre-efectos solo se ejecutan en el cliente — nunca en el servidor.

Los pre-efectos resuelven un problema específico: a veces necesitas medir o guardar el estado del DOM antes de una actualización, y luego usar esa información para realizar una acción después de la actualización. El ejemplo clásico es mantener la posición de desplazamiento en una ventana de chat:

<script>
	let messages = $state([])
	let containerRef = $state()
	let shouldAutoScroll = $state(true)

	$effect.pre(() => {
		// This runs BEFORE the DOM updates with new messages
		if (!containerRef) return

		// Check if user is scrolled to the bottom
		const { scrollTop, scrollHeight, clientHeight } = containerRef
		shouldAutoScroll = scrollHeight - scrollTop <= clientHeight + 50
	})

	$effect(() => {
		// This runs AFTER the DOM updates with new messages
		if (shouldAutoScroll && containerRef) {
			containerRef.scrollTop = containerRef.scrollHeight
		}
	})
</script>

El pre-efecto verifica si el usuario está al final del contenedor de desplazamiento antes de que lleguen nuevos mensajes. Si lo está, establecemos una bandera. El efecto regular se ejecuta después de que el DOM se actualiza (incluyendo los nuevos mensajes) y desplaza hasta el final si la bandera estaba establecida.

Sin los pre-efectos, te enfrentarías a una condición de carrera: para cuando el efecto regular se ejecute, el DOM ya se habrá actualizado y no podrás determinar si el usuario estaba al final antes de la actualización.

Dado que los pre-efectos no se ejecutan en el servidor, cualquier medición del DOM que realicen se difiere de forma segura al cliente. El servidor renderiza con cualquier estado inicial que proporciones, y la lógica del pre-efecto se activa solo después de la hidratación.

La Runa `$props`: Comunicación de Componentes entre Contextos

Las props funcionan de manera idéntica en el servidor y en el cliente — son simplemente valores que se pasan de componentes padre a hijo. Sin embargo, las props aún pueden causar problemas en SSR si los padres pasan valores diferentes en distintos contextos:

<!-- Parent.svelte -->
<script>
	import { browser } from '$app/environment'
	import Child from './Child.svelte'

	// This prop value differs between server and client!
	let screenSize = browser ? (window.innerWidth > 768 ? 'desktop' : 'mobile') : 'unknown'
</script>

<Child {screenSize} />

<!-- Child.svelte -->
<script>
	let { screenSize } = $props()
</script>

<div class="layout" class:mobile={screenSize === 'mobile'}>
	<!-- Content -->
</div>

El padre pasa screenSize = 'unknown' durante SSR y screenSize = 'desktop' o 'mobile' durante la hidratación. El hijo renderiza nombres de clase diferentes, causando una discrepancia de hidratación.

La solución es la misma que con el estado: usar valores predeterminados consistentes y actualizar en efectos:

<!-- Parent.svelte -->
<script>
	import Child from './Child.svelte'

	// Start with a safe default
	let screenSize = $state('desktop') // Reasonable assumption

	$effect(() => {
		// Update to actual value after hydration
		screenSize = window.innerWidth > 768 ? 'desktop' : 'mobile'

		// Keep it updated on resize
		function handleResize() {
			screenSize = window.innerWidth > 768 ? 'desktop' : 'mobile'
		}

		window.addEventListener('resize', handleResize)
		return () => window.removeEventListener('resize', handleResize)
	})
</script>

<Child {screenSize} />

Ahora tanto el servidor como el cliente renderizan inicialmente con screenSize = 'desktop', evitando la discrepancia. Después de la hidratación, el efecto se actualiza al tamaño de pantalla real.

Hooks de Ciclo de Vida: `onMount` y `onDestroy` en el Contexto de SSR

Aunque técnicamente no son runas, los hooks de ciclo de vida merecen mención porque interactúan con SSR de maneras específicas.

onMount solo se ejecuta en el cliente, después de la hidratación. No se ejecuta en el servidor. Esto lo convierte en otro refugio seguro para el código específico del navegador:

<script>
	import { onMount } from 'svelte'

	let chartRef = $state()

	onMount(() => {
		// Safe to use browser APIs here
		// This only runs after hydration
		const chart = new ChartLibrary(chartRef, {
			// chart configuration
		})

		// Return cleanup function
		return () => chart.destroy()
	})
</script>

<div bind:this={chartRef}></div>

La diferencia entre onMount y $effect es sutil pero importante. onMount se ejecuta exactamente una vez después de que el componente se monta. $effect se ejecuta después del montaje y nuevamente cada vez que cambian sus dependencias. Para el código de inicialización que debe ejecutarse una vez, cualquiera de los dos funciona. Para el código que debe responder a cambios de estado, usa $effect.

onDestroy se ejecuta en ambos entornos — en el servidor después del renderizado, y en el cliente cuando el componente se desmonta. Este es el único hook de ciclo de vida que se ejecuta durante SSR. Úsalo para limpiar cualquier recurso asignado durante la ejecución sincrónica del script:

<script>
	import { onDestroy } from 'svelte'

	// If you allocate resources synchronously during SSR...
	const subscription = someGlobalEventBus.subscribe(handleEvent)

	// ...you can clean them up with onDestroy
	onDestroy(() => {
		subscription.unsubscribe()
	})
</script>

En la práctica, rara vez necesitas onDestroy para la limpieza en SSR porque la mayoría de los recursos (elementos del DOM, suscripciones a APIs del navegador, etc.) solo se crean en el cliente a través de efectos o onMount.

El Problema de Discrepancia de Hidratación: Causas, Detección y Soluciones

Las discrepancias de hidratación representan la categoría más común y frustrante de errores en SSR. Exploremos este tema a fondo, entendiendo no solo los síntomas sino las causas subyacentes y las soluciones sistemáticas.

¿Qué Es Exactamente una Discrepancia de Hidratación?

Cuando Svelte hidrata una página, espera que el DOM existente coincida con lo que renderizaría dado el estado actual. El servidor renderizó HTML basándose en el estado al momento del renderizado. El cliente reconstruye el estado del componente durante la hidratación. Si estos estados difieren, el resultado renderizado difiere, creando una discrepancia.

Svelte detecta las discrepancias recorriendo el DOM durante la hidratación y comparando cada elemento con sus expectativas. Cuando encuentra una diferencia — contenido de texto incorrecto, atributo faltante, elemento extra, clase incorrecta — registra una advertencia en modo de desarrollo.

En producción, Svelte intenta recuperarse de manera elegante. Para discrepancias menores (contenido de texto incorrecto), puede simplemente actualizar el DOM para que coincida con las expectativas del cliente. Para discrepancias estructurales (elementos diferentes o hijos faltantes), la recuperación es más complicada y puede resultar en manejadores de eventos rotos o problemas visuales.

La naturaleza insidiosa de las discrepancias de hidratación es que a menudo parecen "funcionar" en producción. La página se renderiza, el contenido parece correcto, todo parece estar bien. Pero acechan errores sutiles: un manejador de eventos adjunto al elemento incorrecto, un estado de componente fuera de sincronía con el estado del DOM, o atributos de accesibilidad en un estado inconsistente.

Categoría 1: Discrepancias Basadas en el Tiempo

El tiempo representa una diferencia fundamental entre los entornos de servidor y cliente. El servidor renderiza en un momento determinado; el cliente hidrata en un momento posterior. Cualquier contenido que dependa de la hora actual puede generar discrepancias.

Considera un componente que muestra tiempos relativos como "hace 5 minutos" o "ayer":

<script>
	let { timestamp } = $props()

	// PROBLEM: "now" is different on server vs client
	function getRelativeTime(ts) {
		const now = Date.now()
		const diff = now - ts

		if (diff < 60000) return 'just now'
		if (diff < 3600000) return `${Math.floor(diff / 60000)} minutes ago`
		if (diff < 86400000) return `${Math.floor(diff / 3600000)} hours ago`
		return 'yesterday'
	}

	let relativeTime = $derived(getRelativeTime(timestamp))
</script>

<span>{relativeTime}</span>

Si el servidor renderiza a las 12:00:00 y el cliente hidrata a las 12:00:05, una marca de tiempo de las 11:59:50 muestra "justo ahora" en el servidor pero "hace 15 segundos" (redondeando a "justo ahora") en el cliente — o si el tiempo cruza un umbral, "justo ahora" vs "hace 1 minuto." ¡Discrepancia!

Solución: Renderizar una representación estable del lado del servidor y mejorarla en el cliente:

<script>
	let { timestamp } = $props()

	// Start with a stable representation that won't mismatch
	// Use the absolute date/time, not relative
	let displayTime = $state(new Date(timestamp).toLocaleString())

	$effect(() => {
		// Update to relative time on the client
		function updateRelativeTime() {
			const now = Date.now()
			const diff = now - timestamp

			if (diff < 60000) {
				displayTime = 'just now'
			} else if (diff < 3600000) {
				displayTime = `${Math.floor(diff / 60000)} minutes ago`
			} else if (diff < 86400000) {
				displayTime = `${Math.floor(diff / 3600000)} hours ago`
			} else {
				displayTime = new Date(timestamp).toLocaleDateString()
			}
		}

		updateRelativeTime()

		// Update periodically for live updates
		const interval = setInterval(updateRelativeTime, 60000)
		return () => clearInterval(interval)
	})
</script>

<time datetime={new Date(timestamp).toISOString()}>
	{displayTime}
</time>

Este enfoque muestra la marca de tiempo absoluta durante SSR (estable, determinista), luego cambia al tiempo relativo después de la hidratación (dinámico, fácil de usar).

Categoría 2: Aleatoriedad y Valores No Deterministas

Cualquier valor que difiera entre computaciones causará discrepancias. El culpable más obvio es Math.random():

<script>
	// PROBLEM: Different random values on server vs client
	let backgroundColor = $state(`hsl(${Math.random() * 360}, 70%, 80%)`)
</script>

<div style="background-color: {backgroundColor}">Random colored box</div>

El servidor genera un matiz aleatorio; el cliente genera uno diferente. ¡Discrepancia!

Solución 1: Pasar valores aleatorios desde el servidor:

La solución más robusta es generar el valor aleatorio en tu función load del servidor y pasarlo como prop. Esto garantiza que tanto el renderizado del servidor como la hidratación del cliente usen exactamente el mismo valor.

// +page.server.js
export function load() {
	return {
		randomHue: Math.random() * 360
	}
}

<!-- +page.svelte -->
<script>
	let { data } = $props()
	let backgroundColor = $derived(`hsl(${data.randomHue}, 70%, 80%)`)
</script>

<div style="background-color: {backgroundColor}">Consistently random colored box</div>

Solución 2: Renderizado en dos pasadas (El Patrón "Mount"):

Si no puedes pasar datos desde el servidor (por ejemplo, dentro de un componente reutilizable), usa un enfoque en dos pasadas. Renderiza un estado predeterminado neutral durante SSR, luego aplica el valor aleatorio solo después del montaje.

<script>
	import { onMount } from 'svelte'

	let hue = $state(0) // Default neutral value
	let initialized = $state(false)

	onMount(() => {
		hue = Math.random() * 360
		initialized = true
	})
</script>

<div
	style="background-color: hsl({hue}, 70%, 80%); transition: background-color 0.3s;"
	style:opacity={initialized ? 1 : 0.5}
>
	Random colored box
</div>

Esto evita la discrepancia porque tanto el servidor como el renderizado inicial del cliente usan hue = 0. La actualización ocurre inmediatamente después del montaje.

Solución 3: Generación de IDs estables:

Para generar IDs únicos (por ejemplo, para atributos de accesibilidad), Svelte 5 todavía no tiene un hook useId integrado como React, pero puedes usar un contador global o crypto.randomUUID() de forma en dos pasadas. Sin embargo, la mejor práctica para IDs de accesibilidad suele ser permitir que el consumidor pase un ID o usar una librería que maneje la generación de IDs estables.

Categoría 3: Detección de Capacidades del Navegador

Diferentes navegadores admiten diferentes funcionalidades. El código que renderiza de manera diferente según las capacidades del navegador causa discrepancias:

<script>
	import { browser } from '$app/environment'

	// PROBLEM: Server doesn't know browser capabilities
	let supportsWebP = $state(false)

	if (browser) {
		const canvas = document.createElement('canvas')
		supportsWebP = canvas.toDataURL('image/webp').startsWith('data:image/webp')
	}
</script>

{#if supportsWebP}
	<img src="/image.webp" alt="..." />
{:else}
	<img src="/image.jpg" alt="..." />
{/if}

El servidor siempre renderiza la imagen de respaldo JPEG. Si el navegador admite WebP, espera la imagen WebP durante la hidratación. ¡Discrepancia!

Solución: Mostrar un estado inicial consistente y detectar las capacidades en el efecto:

<script>
	// null = "still detecting"
	let supportsWebP = $state(null)

	$effect(() => {
		const canvas = document.createElement('canvas')
		supportsWebP = canvas.toDataURL('image/webp').startsWith('data:image/webp')
	})
</script>

<!-- While detecting, show JPEG (consistent with SSR) -->
<!-- After detection, show appropriate format -->
<img src={supportsWebP === true ? '/image.webp' : '/image.jpg'} alt="..." />

Espera — ¡esto aún causa una discrepancia! Después de la hidratación, supportsWebP cambia de null a true, modificando el atributo src.

Mejor solución: Usar el elemento <picture> con el manejo nativo del navegador:

<picture>
	<source srcset="/image.webp" type="image/webp" />
	<source srcset="/image.jpg" type="image/jpeg" />
	<img src="/image.jpg" alt="..." />
</picture>

El elemento <picture> permite que el navegador elija el formato apropiado sin JavaScript. El HTML es idéntico en el servidor y en el cliente, y el navegador selecciona automáticamente WebP si es compatible.

Categoría 4: Diferencias de Configuración Regional e Internacionalización

La configuración regional del servidor a menudo difiere de la del navegador del usuario, causando que los valores formateados no coincidan:

<script>
	let price = $state(1234.56)

	// PROBLEM: Server locale might be en-US, user locale might be de-DE
	// en-US: "$1,234.56"
	// de-DE: "1.234,56 $"
	let formattedPrice = $derived(
		price.toLocaleString(undefined, {
			style: 'currency',
			currency: 'USD'
		})
	)
</script>

<span class="price">{formattedPrice}</span>

Usar undefined para la configuración regional significa "usar la configuración regional predeterminada del entorno." El servidor tiene una predeterminada; el navegador del usuario tiene otra. ¡Discrepancia!

Solución 1: Forzar una configuración regional consistente:

<script>
	let price = $state(1234.56)

	// Always use the same locale
	let formattedPrice = $derived(
		price.toLocaleString('en-US', {
			style: 'currency',
			currency: 'USD'
		})
	)
</script>

Solución 2: Detectar el locale en el cliente y actualizar:

<script>
	let price = $state(1234.56)
	let userLocale = $state('en-US') // Safe default

	$effect(() => {
		userLocale = navigator.language
	})

	let formattedPrice = $derived(
		price.toLocaleString(userLocale, {
			style: 'currency',
			currency: 'USD'
		})
	)
</script>

Esto causa un destello — el formato renderizado por el servidor se muestra brevemente antes de que el formato del cliente tome el control. Para precios, esto puede ser aceptable. Para elementos críticos de la UI, la Solución 1 (locale consistente) suele ser mejor.

Solución 3: Pasar el locale desde el servidor:

Si conoces el locale del usuario en el lado del servidor (a partir de cookies, cabeceras o preferencias del usuario), pásalo a través de las funciones load:

// +page.server.js
export function load({ request }) {
	const acceptLanguage = request.headers.get('accept-language')
	const locale = parseAcceptLanguage(acceptLanguage) || 'en-US'

	return { locale }
}

<!-- +page.svelte -->
<script>
	let { data } = $props()

	let price = $state(1234.56)
	let formattedPrice = $derived(
		price.toLocaleString(data.locale, {
			style: 'currency',
			currency: 'USD'
		})
	)
</script>

Ahora tanto el servidor como el cliente usan el mismo locale, eliminando la discrepancia.

Categoría 5: Diferencias de Viewport y Dispositivo

El servidor no tiene viewport. No puede conocer el tamaño de pantalla del usuario, la densidad de píxeles ni la orientación del dispositivo. El código que renderiza basándose en estos factores genera discrepancias:

<script>
	import { browser } from '$app/environment'

	// PROBLEM: Server can't measure the viewport
	let columns = $state(browser ? (window.innerWidth > 1200 ? 4 : 2) : 3)
</script>

<div class="grid" style="--columns: {columns}">
	<!-- Grid items -->
</div>

El servidor elige 3 columnas como suposición. El cliente podría calcular 4 columnas según el viewport real. ¡Discrepancia!

Solución: Usar CSS para layouts responsivos, no JavaScript:

<div class="grid">
	<!-- Grid items -->
</div>

<style>
	.grid {
		display: grid;
		grid-template-columns: repeat(2, 1fr);
	}

	@media (min-width: 768px) {
		.grid {
			grid-template-columns: repeat(3, 1fr);
		}
	}

	@media (min-width: 1200px) {
		.grid {
			grid-template-columns: repeat(4, 1fr);
		}
	}
</style>

Las media queries de CSS manejan layouts responsivos sin ningún JavaScript. El HTML es idéntico en el servidor y en el cliente; el navegador aplica los estilos apropiados según el tamaño del viewport.

Cuando absolutamente debes usar JavaScript para el layout (quizás para lógica más compleja), acepta que el servidor y el cliente pueden diferir y maneja la transición de forma elegante:

<script>
	import { innerWidth } from 'svelte/reactivity/window'

	// innerWidth.current is undefined during SSR
	// Provide a reasonable desktop default
	let columns = $derived(
		(innerWidth.current ?? 1200) > 1200 ? 4 : (innerWidth.current ?? 1200) > 768 ? 3 : 2
	)
</script>

<div class="grid" style="--columns: {columns}">
	<!-- Grid items -->
</div>

Aquí, por defecto asumimos un viewport de escritorio (1200px+) durante el SSR, lo que da 4 columnas. En móvil, hay un breve destello cuando la grilla se ajusta después de la hidratación. Esto suele ser aceptable porque el layout está cerca de ser correcto y el ajuste es menor.

Patrones para el Acceso Seguro a APIs del Navegador

Hemos establecido que las APIs del navegador no existen en el servidor y deben accederse con cuidado. Desarrollemos un conjunto completo de patrones para escenarios comunes.

Patrón 1: El Wrapper de Effect

El patrón más fundamental envuelve todo el acceso a APIs del navegador en $effect:

<script>
	let scrollPosition = $state(0)
	let viewportHeight = $state(800) // Reasonable default

	$effect(() => {
		// All browser API access happens here
		viewportHeight = window.innerHeight

		function handleScroll() {
			scrollPosition = window.scrollY
		}

		function handleResize() {
			viewportHeight = window.innerHeight
		}

		window.addEventListener('scroll', handleScroll)
		window.addEventListener('resize', handleResize)

		// Initial values
		handleScroll()
		handleResize()

		return () => {
			window.removeEventListener('scroll', handleScroll)
			window.removeEventListener('resize', handleResize)
		}
	})

	let scrollProgress = $derived(scrollPosition / (document.body.scrollHeight - viewportHeight))
</script>

¡Espera — hay un bug arriba! El $derived referencia document.body.scrollHeight, que no existe en el servidor. Vamos a corregirlo:

<script>
	let scrollPosition = $state(0)
	let viewportHeight = $state(800)
	let documentHeight = $state(2000) // Reasonable default

	$effect(() => {
		viewportHeight = window.innerHeight
		documentHeight = document.body.scrollHeight

		function handleScroll() {
			scrollPosition = window.scrollY
			documentHeight = document.body.scrollHeight
		}

		function handleResize() {
			viewportHeight = window.innerHeight
			documentHeight = document.body.scrollHeight
		}

		window.addEventListener('scroll', handleScroll)
		window.addEventListener('resize', handleResize)

		handleScroll()
		handleResize()

		return () => {
			window.removeEventListener('scroll', handleScroll)
			window.removeEventListener('resize', handleResize)
		}
	})

	// Now all values in the derivation are safe
	let scrollProgress = $derived(
		documentHeight <= viewportHeight ? 0 : scrollPosition / (documentHeight - viewportHeight)
	)
</script>

<div class="progress-bar" style="width: {scrollProgress * 100}%"></div>

Patrón 2: Carga Lazy de Módulos del Navegador

Algunas bibliotecas solo funcionan en el navegador. En lugar de importarlas normalmente (lo que fallaría durante el SSR), cárgalas de forma dinámica:

<script>
	let chartContainer = $state()
	let chartInstance = $state(null)

	$effect(() => {
		if (!chartContainer) return

		// Dynamic import only happens on the client
		import('chart.js').then(({ Chart }) => {
			chartInstance = new Chart(chartContainer, {
				type: 'bar',
				data: chartData,
				options: chartOptions
			})
		})

		return () => {
			if (chartInstance) {
				chartInstance.destroy()
			}
		}
	})
</script>

<canvas bind:this={chartContainer}></canvas>

El import() dinámico dentro de $effect es seguro porque los effects no se ejecutan en el servidor. El módulo solo se carga en el navegador.

Patrón 3: El Guard del Navegador con Fallback

A veces quieres usar un valor de una API del navegador pero necesitas un fallback razonable para SSR:

<script>
	import { browser } from '$app/environment'

	// Determine color scheme with SSR-safe fallback
	let prefersDarkMode = $state(false)

	// This runs during SSR (browser is false) and during hydration (browser is true)
	// But the value only updates meaningfully after the effect runs

	$effect(() => {
		const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
		prefersDarkMode = mediaQuery.matches

		function handleChange(e) {
			prefersDarkMode = e.matches
		}

		mediaQuery.addEventListener('change', handleChange)
		return () => mediaQuery.removeEventListener('change', handleChange)
	})
</script>

<div class:dark-mode={prefersDarkMode}>
	<!-- Content -->
</div>

Patrón 4: Uso de Bindings de `svelte:window`

Svelte proporciona una forma declarativa de escuchar eventos de window y hacer binding a propiedades de window usando el elemento <svelte:window>. Esto suele ser más limpio que agregar manualmente event listeners en effects.

<script>
	let innerWidth = $state(0)
	let innerHeight = $state(0)
	let scrollY = $state(0)
	let online = $state(true)

	// Use safe defaults for derived values
	// During SSR, innerWidth will be 0 (or whatever you initialize it to)
	let isMobile = $derived(innerWidth > 0 && innerWidth < 768)
</script>

<svelte:window bind:innerWidth bind:innerHeight bind:scrollY bind:online />

<header class:mobile={isMobile} class:scrolled={scrollY > 50}>
	{#if !online}
		<div class="offline-banner">You are offline</div>
	{/if}
	<!-- Header content -->
</header>

Ten en cuenta que durante el SSR, los bindings no se ejecutan, por lo que tus variables de estado retienen sus valores iniciales. Esto significa que innerWidth será 0 (o lo que hayas definido) en el servidor. Asegúrate de que tu UI maneje esto con elegancia, quizás estableciendo por defecto un layout de escritorio o un estado de carga para evitar cambios de layout si es posible, o aceptando que el layout podría ajustarse después de la hidratación.

Patrón 5: APIs de Almacenamiento (localStorage, sessionStorage)

Las APIs de almacenamiento son exclusivas del navegador y requieren un manejo cuidadoso:

<script>
	// Initial value used for SSR
	let theme = $state('light')

	$effect(() => {
		// Read from storage on mount
		const stored = localStorage.getItem('theme')
		if (stored) {
			theme = stored
		}
	})

	// Separate effect to write changes
	$effect(() => {
		// This effect depends on `theme`
		// It runs whenever theme changes (after the first effect sets it)
		localStorage.setItem('theme', theme)
	})

	function toggleTheme() {
		theme = theme === 'light' ? 'dark' : 'light'
	}
</script>

<button onclick={toggleTheme}>
	Current theme: {theme}
</button>

Hay un problema sutil aquí: el segundo effect se ejecuta inmediatamente después del primero, escribiendo el valor inicial en el almacenamiento antes de que hayamos leído de él. Vamos a corregirlo:

<script>
	let theme = $state('light')
	let initialized = $state(false)

	$effect(() => {
		// Read from storage
		const stored = localStorage.getItem('theme')
		if (stored) {
			theme = stored
		}
		initialized = true
	})

	$effect(() => {
		// Only write after initialization
		if (!initialized) return
		localStorage.setItem('theme', theme)
	})
</script>

O de forma más elegante, combina la lectura y la escritura en un único effect que rastrea los cambios:

<script>
	let theme = $state('light')

	$effect(() => {
		// Read initial value
		const stored = localStorage.getItem('theme')
		if (stored && stored !== theme) {
			theme = stored
		}

		// Track future changes
		return () => {
			localStorage.setItem('theme', theme)
		}
	})
</script>

Hmm, esto aún tiene problemas con la función de limpieza capturando valores desactualizados. Aquí hay un enfoque más limpio usando dos effects con una bandera:

<script>
	let theme = $state('light')
	let hasLoadedFromStorage = false

	$effect(() => {
		// First run: load from storage
		if (!hasLoadedFromStorage) {
			const stored = localStorage.getItem('theme')
			if (stored) {
				theme = stored
			}
			hasLoadedFromStorage = true
			return
		}

		// Subsequent runs: save to storage
		localStorage.setItem('theme', theme)
	})
</script>

En realidad, el patrón más limpio usa untrack para evitar que la lectura del valor inicial dispare un guardado:

<script>
	import { untrack } from 'svelte'

	let theme = $state('light')

	// Load from storage once
	$effect(() => {
		const stored = localStorage.getItem('theme')
		if (stored) {
			theme = stored
		}
	})

	// Save to storage on changes
	$effect(() => {
		const currentTheme = theme // Read theme (creates dependency)

		// Avoid saving on first run
		untrack(() => {
			// Small delay to ensure we don't save the initial value
			const timeout = setTimeout(() => {
				localStorage.setItem('theme', currentTheme)
			}, 0)

			return () => clearTimeout(timeout)
		})
	})
</script>

¡Esto se está complicando! Para código en producción, considera extraer esto en una utilidad reutilizable:

// lib/persisted.svelte.js
export function createPersistedState(key, initialValue) {
	let value = $state(initialValue)
	let loaded = false

	$effect(() => {
		if (!loaded) {
			const stored = localStorage.getItem(key)
			if (stored !== null) {
				try {
					value = JSON.parse(stored)
				} catch {
					value = stored
				}
			}
			loaded = true
		} else {
			localStorage.setItem(key, JSON.stringify(value))
		}
	})

	return {
		get value() {
			return value
		},
		set value(v) {
			value = v
		}
	}
}

<script>
	import { createPersistedState } from '$lib/persisted.svelte.js'

	const theme = createPersistedState('theme', 'light')
</script>

<button onclick={() => (theme.value = theme.value === 'light' ? 'dark' : 'light')}>
	Theme: {theme.value}
</button>

Patrón 6: Canvas y WebGL

Las operaciones con Canvas requieren acceso al DOM y deben diferirse completamente:

<script>
	let canvasRef = $state()
	let animationFrame = $state(null)

	$effect(() => {
		if (!canvasRef) return

		const ctx = canvasRef.getContext('2d')
		if (!ctx) return

		// Animation loop
		function draw(timestamp) {
			ctx.clearRect(0, 0, canvasRef.width, canvasRef.height)

			// Draw your scene
			const x = (timestamp / 10) % canvasRef.width
			ctx.fillStyle = 'blue'
			ctx.fillRect(x, 50, 50, 50)

			animationFrame = requestAnimationFrame(draw)
		}

		animationFrame = requestAnimationFrame(draw)

		return () => {
			if (animationFrame) {
				cancelAnimationFrame(animationFrame)
			}
		}
	})
</script>

<canvas bind:this={canvasRef} width="400" height="200">
	<!-- Fallback content for SSR and non-canvas browsers -->
	<p>Animated canvas demonstration</p>
</canvas>

El elemento <canvas> se renderiza durante el SSR con su contenido de fallback. Después de la hidratación, el effect toma el control y comienza a dibujar.

Patrón 7: Intersection Observer para Carga Lazy

Intersection Observer se usa comúnmente para carga lazy, scroll infinito y animaciones activadas por scroll:

<script>
	let { src, alt } = $props()

	let imgRef = $state()
	let isVisible = $state(false)
	let hasLoaded = $state(false)

	$effect(() => {
		if (!imgRef) return

		const observer = new IntersectionObserver(
			(entries) => {
				entries.forEach((entry) => {
					if (entry.isIntersecting) {
						isVisible = true
						observer.disconnect() // Only need to load once
					}
				})
			},
			{
				rootMargin: '100px', // Start loading 100px before visible
				threshold: 0
			}
		)

		observer.observe(imgRef)

		return () => observer.disconnect()
	})
</script>

<div class="image-container" bind:this={imgRef}>
	{#if isVisible}
		<img {src} {alt} onload={() => (hasLoaded = true)} class:loaded={hasLoaded} />
	{:else}
		<!-- Placeholder shown during SSR and before intersection -->
		<div class="placeholder" aria-hidden="true"></div>
	{/if}
</div>

<style>
	.image-container {
		min-height: 200px; /* Prevent layout shift */
	}

	img {
		opacity: 0;
		transition: opacity 0.3s;
	}

	img.loaded {
		opacity: 1;
	}

	.placeholder {
		background: #e0e0e0;
		height: 200px;
	}
</style>

Controlando el SSR a Nivel de Página

SvelteKit proporciona opciones de página para controlar el comportamiento del SSR en páginas específicas. Entender estas opciones te ayuda a tomar decisiones informadas sobre dónde aplicar SSR.

La Opción `ssr`

Establecer ssr = false deshabilita el renderizado del lado del servidor para una página:

// +page.js
export const ssr = false

Con esta configuración, el servidor devuelve una carcasa HTML mínima sin contenido pre-renderizado. La página completa es renderizada por JavaScript en el navegador.

Cuándo usar ssr = false:

Páginas que fundamentalmente no pueden funcionar sin APIs del navegador (por ejemplo, un juego basado en WebGL)
Paneles de administración protegidos por autenticación donde el SEO no importa
Páginas con interacciones complejas solo del lado del cliente donde SSR no agrega valor

Compensaciones:

Sin contenido hasta que JavaScript cargue y se ejecute (perjudicial para la percepción del rendimiento)
Sin beneficio de SEO — los motores de búsqueda ven una página vacía
Los usuarios con JavaScript deshabilitado no ven nada
Se pierden los beneficios de mejora progresiva y accesibilidad

Use esta opción con moderación. La mayoría de las páginas se benefician del SSR, y los patrones que hemos discutido le permiten manejar características exclusivas del navegador manteniendo el SSR habilitado.

La Opción `csr`

Establecer csr = false deshabilita el renderizado del lado del cliente (hidratación):

// +page.js
export const csr = false

La página se renderiza en el servidor y se envía como HTML estático. No se envía JavaScript; no ocurre hidratación.

Cuándo usar csr = false:

Páginas de contenido puramente estático (acerca de, términos de servicio, política de privacidad)
Publicaciones de blog y artículos que no necesitan interactividad
Páginas donde minimizar JavaScript es crítico

Compensaciones:

Sin interactividad — los botones no funcionan, los formularios se envían de forma tradicional, no hay JavaScript en absoluto
Sin navegación del lado del cliente — cada enlace provoca una recarga completa de la página
Puede mejorar dramáticamente el rendimiento para las páginas apropiadas

La Opción `prerender`

El pre-renderizado genera HTML en tiempo de compilación en lugar de en tiempo de solicitud:

// +page.js
export const prerender = true

Durante npm run build, SvelteKit recorre su sitio, renderiza las páginas pre-renderizables y las guarda como archivos HTML estáticos.

Cuándo usar prerender = true:

Páginas con contenido que no cambia por solicitud (publicaciones de blog, documentación)
Páginas de marketing que son iguales para todos los usuarios
Cualquier página que pueda almacenarse en caché y servirse como archivos estáticos

Compensaciones:

El contenido se fija en tiempo de compilación — el contenido dinámico requiere reconstrucciones
No se pueden usar cookies, encabezados ni datos específicos de la solicitud durante el pre-renderizado
Aún se hidrata en el cliente a menos que csr = false también esté establecido

Puede combinar estas opciones para un control más preciso:

// A truly static page: no JavaScript, pre-built at compile time
export const prerender = true
export const csr = false

// A fully dynamic page: no SSR, entirely client-rendered
export const ssr = false
// (csr is true by default)

Patrones y Técnicas Avanzadas de SSR

Exploremos algunos patrones sofisticados para manejar escenarios complejos de SSR.

Carga Condicional de Componentes

Algunos componentes simplemente no pueden funcionar durante el SSR — dependen demasiado de APIs del navegador, bibliotecas de terceros o condiciones específicas de ejecución. Puede omitir completamente su renderizado durante el SSR:

<script>
	import { browser } from '$app/environment'
	import HeavyBrowserComponent from './HeavyBrowserComponent.svelte'
</script>

{#if browser}
	<HeavyBrowserComponent />
{:else}
	<div class="placeholder" aria-label="Loading interactive feature">
		<p>Interactive feature loading...</p>
	</div>
{/if}

El servidor renderiza el marcador de posición. El cliente lo reemplaza con el componente real después de la hidratación. Esto no es una discrepancia porque Svelte sabe que browser cambia entre el servidor y el cliente.

Para un rendimiento aún mejor, use importaciones dinámicas para evitar descargar código exclusivo del navegador en el servidor:

<script>
	import { browser } from '$app/environment'

	let HeavyComponent = $state(null)

	if (browser) {
		import('./HeavyBrowserComponent.svelte').then((module) => {
			HeavyComponent = module.default
		})
	}
</script>

{#if HeavyComponent}
	<svelte:component this={HeavyComponent} />
{:else}
	<div class="placeholder">Loading...</div>
{/if}

En realidad, con Svelte 5 podemos usar el componente directamente:

<script>
	import { browser } from '$app/environment'

	let Component = $state(null)

	$effect(() => {
		import('./HeavyBrowserComponent.svelte').then((module) => {
			Component = module.default
		})
	})
</script>

{#if Component}
	<Component />
{:else}
	<div class="placeholder">Loading...</div>
{/if}

Traspaso de Estado Servidor-Cliente

A veces necesita pasar valores calculados del servidor al cliente sin volver a calcularlos. La forma estándar de SvelteKit para hacer esto es mediante props data.

// +page.server.js
export async function load({ fetch }) {
	const rawData = await fetchLargeDataset()
	const processedData = expensiveTransformation(rawData)

	return {
		processedData
	}
}

<!-- +page.svelte -->
<script>
	let { data } = $props()
</script>

<DataVisualization data={data.processedData} />

El servidor ejecuta expensiveTransformation, serializa el resultado en los datos de la página y el cliente lo recibe listo para usar. Esto evita ejecutar lógica costosa en el cliente y garantiza la consistencia.

Este patrón es particularmente valioso para:

Resultados de modelos de aprendizaje automático
Cálculos complejos o agregaciones
Datos que requieren autenticación del lado del servidor para ser obtenidos
Cualquier cosa costosa que no debería ejecutarse dos veces

Manejo del Estado de Autenticación

La autenticación suele residir en cookies (accesibles durante el SSR) pero necesita manejo del lado del cliente para la renovación de tokens, cierre de sesión, etc.:

<!-- +layout.svelte -->
<script>
	import { page } from '$app/state'

	// User data from server-side load function
	let user = $derived(page.data.user)

	// Client-side session management
	let sessionExpiresAt = $state(null)
	let isRefreshing = $state(false)

	$effect(() => {
		if (!user) return

		// Parse session expiry from JWT or stored value
		const token = document.cookie
			.split('; ')
			.find((row) => row.startsWith('session='))
			?.split('=')[1]

		if (token) {
			try {
				const payload = JSON.parse(atob(token.split('.')[1]))
				sessionExpiresAt = new Date(payload.exp * 1000)
			} catch {
				// Invalid token format
			}
		}

		// Set up automatic refresh before expiry
		function checkAndRefresh() {
			if (!sessionExpiresAt) return

			const timeUntilExpiry = sessionExpiresAt.getTime() - Date.now()

			if (timeUntilExpiry < 60000 && !isRefreshing) {
				isRefreshing = true

				fetch('/api/auth/refresh', { method: 'POST' })
					.then((res) => res.json())
					.then((data) => {
						sessionExpiresAt = new Date(data.expiresAt)
					})
					.finally(() => {
						isRefreshing = false
					})
			}
		}

		const interval = setInterval(checkAndRefresh, 30000)
		checkAndRefresh()

		return () => clearInterval(interval)
	})
</script>

<slot />

Componentes Portal

Los portales renderizan contenido fuera de la jerarquía DOM del componente, típicamente para modales, tooltips o menús desplegables. Requieren manipulación del DOM:

<!-- Modal.svelte -->
<script>
	import { browser } from '$app/environment'

	let { open = $bindable(false), children } = $props()
	let portalTarget = $state(null)

	$effect(() => {
		// Create portal container
		const container = document.createElement('div')
		container.className = 'modal-portal'
		container.setAttribute('role', 'presentation')
		document.body.appendChild(container)
		portalTarget = container

		return () => {
			container.remove()
		}
	})

	$effect(() => {
		if (!browser) return

		if (open) {
			document.body.style.overflow = 'hidden'

			// Focus trap and escape key handling
			function handleKeydown(e) {
				if (e.key === 'Escape') {
					open = false
				}
			}

			document.addEventListener('keydown', handleKeydown)

			return () => {
				document.body.style.overflow = ''
				document.removeEventListener('keydown', handleKeydown)
			}
		}
	})
</script>

{#if open && portalTarget}
	<!-- Content rendered into portal via Svelte's own rendering -->
	<div class="modal-overlay" onclick={() => (open = false)}>
		<div class="modal-content" role="dialog" aria-modal="true" onclick={(e) => e.stopPropagation()}>
			{@render children()}
		</div>
	</div>
{/if}

El modal no se renderiza durante el SSR (no hay portalTarget), lo cual es apropiado ya que los modales típicamente comienzan cerrados.

Gestión del Foco

La gestión del foco es completamente del lado del cliente pero importante para la accesibilidad:

<script>
	let { isOpen = $bindable(false) } = $props()
	let closeButtonRef = $state()
	let previousActiveElement = $state(null)

	$effect(() => {
		if (isOpen) {
			// Save current focus
			previousActiveElement = document.activeElement

			// Focus the modal
			closeButtonRef?.focus()

			return () => {
				// Restore focus when closing
				previousActiveElement?.focus()
			}
		}
	})
</script>

{#if isOpen}
	<div class="modal">
		<button bind:this={closeButtonRef} onclick={() => (isOpen = false)}> Close </button>
		<!-- Modal content -->
	</div>
{/if}

Depuración de Problemas de SSR

Cuando ocurren problemas de SSR, necesita enfoques de depuración sistemáticos.

Registro con Conciencia del Entorno

Agregue registros que distingan el servidor del cliente:

<script>
	import { browser, dev } from '$app/environment'

	function log(message, ...args) {
		if (!dev) return // Only log in development

		const prefix = browser ? '🌐 [Browser]' : '🖥️ [Server]'
		const timestamp = new Date().toISOString().substr(11, 12)
		console.log(`${prefix} ${timestamp} ${message}`, ...args)
	}

	log('Component initializing')

	let count = $state(0)
	log('State initialized', { count })

	$effect(() => {
		log('Effect running')
	})
</script>

Detección de Discrepancias de Hidratación

Svelte registra las discrepancias de hidratación en la consola durante el desarrollo. Para hacerlas más prominentes:

// hooks.client.js
const originalWarn = console.warn
console.warn = (...args) => {
	if (args[0]?.includes?.('hydrat')) {
		console.error('🚨 HYDRATION MISMATCH:', ...args)
		// Optionally trigger a debugger breakpoint
		// debugger;
	}
	originalWarn.apply(console, args)
}

Mensajes de Error Comunes Explicados

"window is not defined" o "document is not defined": Está accediendo a variables globales del navegador durante el SSR. Mueva el código a un $effect o protéjalo con if (browser).

"localStorage is not defined": El mismo problema — localStorage es exclusivo del navegador. Use un efecto para acceder a él.

"Hydration completed but contains mismatches": El HTML renderizado por el servidor no coincide con lo que el cliente esperaba. Verifique si hay valores dependientes del tiempo, valores aleatorios, renderizado específico del navegador o diferencias de configuración regional.

"Cannot read property 'X' of undefined": Ocurre con frecuencia al acceder a elementos DOM antes de que estén disponibles. Asegúrese de que sus referencias bind:this estén pobladas antes de usarlas.

Resumen de Buenas Prácticas

Consolidemos lo que hemos aprendido en directrices accionables:

Siempre proporcione valores predeterminados seguros para SSR. Cada fragmento de estado debe tener un valor predeterminado razonable que tenga sentido en el servidor. No asuma que las APIs del navegador existen durante la inicialización.

Use $effect como su santuario de APIs del navegador. Cualquier código que requiera APIs del navegador pertenece a un efecto. Los efectos nunca se ejecutan en el servidor, lo que los hace intrínsecamente seguros para el código específico del navegador.

Adopte svelte/reactivity/window para valores reactivos de la ventana. Estas utilidades manejan el SSR automáticamente y proporcionan actualizaciones reactivas sin gestión manual de listeners de eventos.

Pruebe con JavaScript deshabilitado. Su HTML renderizado por el servidor debe ser significativo y funcional. Si no lo es, está perdiendo los beneficios del SSR.

Sea deliberado sobre las expectativas de hidratación. Pregúntese: "¿Esto se renderizará de forma idéntica en el servidor y en el cliente?" Si no es así, reestructure para garantizar la consistencia o acepte la transición.

Prefiera CSS para diseños responsivos. Las media queries no causan discrepancias de hidratación. La lógica responsiva basada en JavaScript sí.

Proteja el contenido sensible al tiempo. Use representaciones estables durante el SSR y mejore con valores dinámicos después de la hidratación.

Tenga en cuenta las opciones de página. ssr, csr y prerender le dan un control preciso. Úselas deliberadamente según las necesidades de cada página.

Registre con conciencia del entorno. Al depurar, saber si el código se ejecutó en el servidor o en el cliente es invaluable.

Conclusión

El renderizado del lado del servidor con el sistema de runas de Svelte 5 requiere un cambio fundamental en la forma de pensar. Ya no está escribiendo código que se ejecuta en un único entorno; está escribiendo código que debe funcionar correctamente en dos contextos fundamentalmente diferentes, en dos momentos distintos, con dos conjuntos diferentes de APIs disponibles.

La idea clave es que los problemas de SSR no son misteriosos ni impredecibles una vez que comprende la mecánica subyacente. El servidor renderiza de forma sincrónica, produce HTML y descarta el estado. El cliente se hidrata, esperando que el DOM coincida con sus expectativas. Los efectos solo se ejecutan en el cliente. Las APIs del navegador solo existen en el cliente. Con esta comprensión, puede anticipar los problemas antes de que ocurran y diseñar componentes que funcionen correctamente desde el principio.

Los patrones que hemos explorado — acceso a APIs del navegador basado en efectos, valores predeterminados seguros para SSR, hydratable para valores sincronizados, diseño responsivo basado en CSS — no son convenciones arbitrarias. Son consecuencias lógicas de la naturaleza fundamental del SSR. Cuando entiende por qué estos patrones funcionan, puede adaptarlos a situaciones nuevas y depurar problemas de manera efectiva.

El renderizado del lado del servidor no es solo una optimización de rendimiento o una técnica de SEO. Es un compromiso con la construcción de aplicaciones resilientes que funcionen para todos: conexiones rápidas y lentas, dispositivos potentes y débiles, JavaScript habilitado y deshabilitado, motores de búsqueda y lectores de pantalla. La complejidad que hemos navegado es el precio de esa resiliencia, y es un precio que vale la pena pagar.

Sus aplicaciones Svelte 5 ahora pueden cruzar con confianza la frontera servidor-cliente, ofreciendo cargas iniciales rápidas mientras habilitan una rica interactividad. Los inconvenientes son conocidos, los patrones están establecidos y usted tiene el modelo mental para manejar cualquier desafío que surja. Construya con confianza.

Problemas Comunes del Renderizado del Lado del Servidor con Runes en Svelte 5

El Paradigma de la Aplicación Universal

Entendiendo la Naturaleza Fundamental de las Aplicaciones Universales

¿Por Qué Existe Esta Arquitectura?

Los Dos Entornos: Una Comparación Detallada

La Línea de Tiempo de SSR: Un Análisis Momento a Momento

Fase 1: El Servidor Recibe una Solicitud

Fase 2: Ejecución de Componentes en el Servidor

Fase 3: Entrega del HTML al Navegador

Fase 4: Carga y Análisis de JavaScript

Fase 5: Hidratación

Fase 6: Navegación del Lado del Cliente

Análisis Profundo: Cómo Se Comporta Cada Rune Durante SSR

El Rune $state: Inicialización de Estado Reactivo

El Rune $derived: Valores Computados y Sus Dependencias

El Rune $effect: Tu Puerto Seguro para Código del Navegador

La Runa $effect.pre: Efectos Secundarios Antes de la Actualización del DOM

La Runa $props: Comunicación de Componentes entre Contextos

Hooks de Ciclo de Vida: onMount y onDestroy en el Contexto de SSR

El Problema de Discrepancia de Hidratación: Causas, Detección y Soluciones

¿Qué Es Exactamente una Discrepancia de Hidratación?

Categoría 1: Discrepancias Basadas en el Tiempo

Categoría 2: Aleatoriedad y Valores No Deterministas

Categoría 3: Detección de Capacidades del Navegador

Categoría 4: Diferencias de Configuración Regional e Internacionalización

Categoría 5: Diferencias de Viewport y Dispositivo

Patrones para el Acceso Seguro a APIs del Navegador

Patrón 1: El Wrapper de Effect

Patrón 2: Carga Lazy de Módulos del Navegador

Patrón 3: El Guard del Navegador con Fallback

Patrón 4: Uso de Bindings de svelte:window

Patrón 5: APIs de Almacenamiento (localStorage, sessionStorage)

Patrón 6: Canvas y WebGL

Patrón 7: Intersection Observer para Carga Lazy

Controlando el SSR a Nivel de Página

La Opción ssr

La Opción csr

La Opción prerender

Patrones y Técnicas Avanzadas de SSR

Carga Condicional de Componentes

Traspaso de Estado Servidor-Cliente

Manejo del Estado de Autenticación

Componentes Portal

Gestión del Foco

Depuración de Problemas de SSR

Registro con Conciencia del Entorno

Detección de Discrepancias de Hidratación

Mensajes de Error Comunes Explicados

Resumen de Buenas Prácticas

Conclusión

El Rune `$state`: Inicialización de Estado Reactivo

El Rune `$derived`: Valores Computados y Sus Dependencias

El Rune `$effect`: Tu Puerto Seguro para Código del Navegador

La Runa `$effect.pre`: Efectos Secundarios Antes de la Actualización del DOM

La Runa `$props`: Comunicación de Componentes entre Contextos

Hooks de Ciclo de Vida: `onMount` y `onDestroy` en el Contexto de SSR

Patrón 4: Uso de Bindings de `svelte:window`

La Opción `ssr`

La Opción `csr`

La Opción `prerender`