Una Guía Completa sobre Eventos de Ventana y Bindings Reactivos

El objeto window del navegador actúa como puerta de entrada entre tu aplicación y el viewport del usuario, los dispositivos de entrada y la sesión de navegación. En el desarrollo tradicional con JavaScript, interactuar con window requiere una gestión cuidadosa del ciclo de vida: agregar event listeners en el momento correcto, eliminarlos para prevenir fugas de memoria, y manejar las particularidades del renderizado del lado del servidor donde window simplemente no existe.

El elemento especial <svelte:window> de Svelte 5 abstrae estas complejidades de manera elegante, proporcionando una interfaz declarativa que se siente natural dentro del modelo de componentes, al tiempo que maneja automáticamente la limpieza y la seguridad con SSR.

Este tutorial examina <svelte:window> desde sus conceptos fundamentales hasta patrones arquitectónicos avanzados. Exploraremos no solo cómo usar este elemento, sino cuándo utilizarlo versus alternativas como el módulo svelte/reactivity/window, y cómo diseñar componentes que respondan con elegancia a los cambios de estado de la ventana sin introducir cuellos de botella en el rendimiento ni anti-patrones arquitectónicos.

Entendiendo el Espacio del Problema

Por Qué Importa el Manejo Especial de Window

Antes de profundizar en <svelte:window> en sí, entendamos los desafíos que aborda. Considera lo que ocurre cuando quieres responder a atajos de teclado en una aplicación JavaScript tradicional:

// Traditional approach - fraught with potential issues
class KeyboardHandler {
	constructor(callback) {
		this.callback = callback
		this.handleKeydown = this.handleKeydown.bind(this)
		window.addEventListener('keydown', this.handleKeydown)
	}

	handleKeydown(event) {
		if (event.key === 'Escape') {
			this.callback('escape-pressed')
		}
	}

	destroy() {
		// Easy to forget this, leading to memory leaks
		window.removeEventListener('keydown', this.handleKeydown)
	}
}

Este patrón introduce varios modos de falla que los desarrolladores encuentran frecuentemente. El método destroy debe ser llamado explícitamente, y olvidar hacerlo crea fugas de memoria donde los event listeners persisten incluso después de que el componente conceptualmente ya no existe.

En contextos de renderizado del lado del servidor, este código lanza errores porque window es undefined. El patrón de binding con this agrega carga cognitiva, y gestionar múltiples tipos de eventos multiplica esta complejidad.

Los elementos especiales de Svelte transforman esta complejidad imperativa en simplicidad declarativa, manteniendo al mismo tiempo el enfoque característico del framework para la limpieza automática.

La Anatomía de `<svelte:window>`

Acceso Declarativo a Window

El elemento <svelte:window> existe puramente en tiempo de compilación—no produce salida en el DOM y no puede contener hijos. Su único propósito es proporcionar una superficie declarativa para adjuntar event handlers y bindings al objeto window:

<svelte:window onevent={handler} />
<svelte:window bind:property={value} />

El elemento debe aparecer en el nivel superior de tu componente, lo que significa que no puede estar anidado dentro de bloques condicionales, bucles u otros elementos. Esta restricción existe porque Svelte necesita configurar y desconfigurar estos bindings durante la inicialización y la destrucción del componente, respectivamente.

Examinemos un ejemplo fundamental que demuestra la mecánica central:

<script>
	let lastKeyPressed = $state('')
	let keyPressCount = $state(0)

	function handleKeydown(event) {
		lastKeyPressed = event.key
		keyPressCount += 1
	}
</script>

<svelte:window onkeydown={handleKeydown} />

<div class="keyboard-monitor">
	<p>Last key pressed: <code>{lastKeyPressed || 'None'}</code></p>
	<p>Total key presses: {keyPressCount}</p>
</div>

Cuando Svelte compila este componente, genera código que agrega el event listener cuando el componente se monta y lo elimina cuando el componente se desmonta. Esto ocurre automáticamente—no se requiere limpieza manual, no hay método de ciclo de vida que recordar, no hay oportunidad de fugas de memoria por una limpieza olvidada.

Patrones de Manejo de Eventos

<svelte:window> admite todos los eventos DOM estándar que emite el objeto window. Esto incluye eventos de teclado (keydown, keyup), eventos de mouse (scroll, resize), eventos de foco (focus, blur), y muchos otros.

Entendiendo las Firmas de los Event Handlers

Los event handlers de window reciben el objeto de evento DOM estándar, lo que te permite acceder a todas las propiedades y métodos nativos. La convención de nomenclatura de eventos en Svelte 5 usa el prefijo on seguido del nombre del evento en minúsculas:

<script>
	let scrollY = $state(0)
	let scrollDirection = $state('none')
	let previousScrollY = 0

	function handleScroll(event) {
		// event.currentTarget is window in this context
		const currentScrollY = window.scrollY

		if (currentScrollY > previousScrollY) {
			scrollDirection = 'down'
		} else if (currentScrollY < previousScrollY) {
			scrollDirection = 'up'
		}

		previousScrollY = currentScrollY
		scrollY = currentScrollY
	}
</script>

<svelte:window onscroll={handleScroll} />

<header class={{ scrolled: scrollY > 50, hide: scrollDirection === 'down' && scrollY > 100 }}>
	<nav>Navigation content</nav>
</header>

<style>
	header {
		position: fixed;
		top: 0;
		transition: transform 0.3s ease;
	}

	header.scrolled {
		background: rgba(255, 255, 255, 0.95);
		box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
	}

	header.hide {
		transform: translateY(-100%);
	}
</style>

Este patrón implementa un "encabezado inteligente" que se oculta al desplazarse hacia abajo y se revela al desplazarse hacia arriba—un patrón de UX común que requiere rastrear no solo la posición de scroll sino también la dirección del mismo.

Múltiples Event Handlers y Composición de Eventos

Puedes adjuntar múltiples handlers al mismo elemento listándolos por separado o combinándolos. Svelte 5 permite múltiples handlers para el mismo tipo de evento:

<script>
  import { analyticsTracker } from './analytics.js';

  let windowFocused = $state(true);
  let lastActivity = $state(Date.now());

  function handleFocus() {
    windowFocused = true;
    lastActivity = Date.now();
  }

  function handleBlur() {
    windowFocused = false;
  }

  function handleActivity() {
    lastActivity = Date.now();
  }

  function trackInteraction(event) {
    analyticsTracker.recordInteraction({
      type: event.type,
      timestamp: Date.now(),
      windowFocused
    });
  }
</script>

<svelte:window
  onfocus={handleFocus}
  onblur={handleBlur}
  onmousemove={handleActivity}
  onkeydown={handleActivity}
  onclick={trackInteraction}
  onkeydown={trackInteraction}
/>

{#if !windowFocused}
  <div class="pause-overlay">
    <p>Application paused</p>
    <p>Click to resume</p>
  </div>
{/if}

Observa que onkeydown aparece dos veces—una para el seguimiento de actividad y otra para analíticas. Svelte 5 maneja esto llamando a ambos handlers cuando el evento se dispara. Este patrón de composición te permite separar responsabilidades sin crear funciones handler que hagan demasiadas cosas.

Modificadores de Eventos y Manejo en Fase de Captura

Los modificadores de eventos de Svelte funcionan con <svelte:window> igual que con los elementos regulares. El modificador capture es particularmente útil para eventos de window cuando necesitas interceptar eventos antes de que lleguen a sus objetivos:

<script>
	let interceptedKeys = $state([])

	function interceptKeydown(event) {
		// Capture phase fires before the target receives the event
		if (event.key === 'Tab' && event.shiftKey) {
			// Implement custom focus management
			event.preventDefault()
			handleReverseFocusNavigation()
		}

		interceptedKeys = [...interceptedKeys.slice(-9), event.key]
	}

	function handleReverseFocusNavigation() {
		// Custom focus logic here
	}
</script>

<svelte:window onkeydowncapture={interceptKeydown} />

<div class="key-log">
	<h3>Recent keys (captured):</h3>
	<ul>
		{#each interceptedKeys as key}
			<li><kbd>{key}</kbd></li>
		{/each}
	</ul>
</div>

La fase de captura resulta esencial al construir componentes accesibles que necesitan gestionar el foco antes de que ocurra el comportamiento predeterminado del navegador. Al usar onkeydowncapture en lugar de onkeydown, el handler se dispara durante la fase de captura, dándote acceso prioritario al evento.

Bindings Reactivos de Window:

Sincronizando el Estado del Componente con el Estado del Navegador

Más allá del manejo de eventos, <svelte:window> proporciona bindings a propiedades específicas de window. Estos bindings se dividen en dos categorías: bindings de solo lectura que reflejan el estado del navegador, y bindings bidireccionales que pueden tanto leer como modificar el estado del navegador.

Entendiendo las Propiedades Enlazables

Las siguientes propiedades pueden enlazarse a <svelte:window>:

Bindings de solo lectura (que reflejan el estado actual de la ventana):

innerWidth - El ancho interior de la ventana en píxeles
innerHeight - El alto interior de la ventana en píxeles
outerWidth - El ancho completo de la ventana del navegador incluyendo elementos de la interfaz
outerHeight - El alto completo de la ventana del navegador incluyendo elementos de la interfaz
online - Un alias para navigator.onLine, que indica la conectividad de red
devicePixelRatio - La relación entre píxeles físicos y píxeles CSS

Bindings bidireccionales (pueden leerse y modificarse):

scrollX - Posición de scroll horizontal (puede establecerse para hacer scroll programáticamente)
scrollY - Posición de scroll vertical (puede establecerse para hacer scroll programáticamente)

La naturaleza de solo lectura de la mayoría de los bindings refleja una verdad fundamental: tu componente no puede cambiar las dimensiones de la ventana ni el estado de red del usuario. Solo puedes observar estos valores y responder en consecuencia.

Construyendo Componentes Responsivos con Bindings de Dimensiones

Los bindings de dimensiones habilitan comportamiento responsivo que va más allá de las media queries de CSS. Considera un escenario donde necesitas renderizar diferentes estructuras de componentes según el tamaño del viewport:

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

	// Derived breakpoint logic
	let breakpoint = $derived(
		innerWidth < 640
			? 'mobile'
			: innerWidth < 1024
				? 'tablet'
				: innerWidth < 1440
					? 'desktop'
					: 'wide'
	)

	let orientation = $derived(innerHeight > innerWidth ? 'portrait' : 'landscape')

	// Calculate optimal grid columns based on actual width
	let optimalColumns = $derived(Math.max(1, Math.floor(innerWidth / 300)))
</script>

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

<div class="dashboard" style:--columns={optimalColumns}>
	{#if breakpoint === 'mobile'}
		<MobileNavigation />
	{:else}
		<DesktopSidebar collapsed={breakpoint === 'tablet'} />
	{/if}

	<main class="content">
		<header class="metrics">
			<span>Viewport: {innerWidth}×{innerHeight}</span>
			<span>Breakpoint: {breakpoint}</span>
			<span>Orientation: {orientation}</span>
		</header>

		<div class="grid">
			{#each items as item}
				<GridItem {item} compact={breakpoint === 'mobile'} />
			{/each}
		</div>
	</main>
</div>

<style>
	.grid {
		display: grid;
		grid-template-columns: repeat(var(--columns), 1fr);
		gap: 1rem;
	}
</style>

Este patrón ofrece varias ventajas sobre los enfoques puramente de CSS. Primero, puedes renderizar condicionalmente árboles de componentes completamente diferentes en lugar de solo ocultar elementos. Segundo, puedes pasar información de breakpoints a componentes hijos como props, habilitando un comportamiento responsivo coordinado. Tercero, puedes calcular valores derivados como el número óptimo de columnas que dependen de dimensiones exactas en píxeles.

Bindings de Posición de Scroll: Implementando Comportamientos de Scroll Complejos

Los bindings scrollX y scrollY merecen atención especial porque son bidireccionales—puedes tanto leer la posición de scroll actual como establecerla para hacer scroll programáticamente:

<script>
	let scrollY = $state(0)
	let targetSection = $state(null)

	// Section positions would typically be calculated dynamically
	const sections = [
		{ id: 'intro', name: 'Introduction', offset: 0 },
		{ id: 'features', name: 'Features', offset: 800 },
		{ id: 'pricing', name: 'Pricing', offset: 1600 },
		{ id: 'contact', name: 'Contact', offset: 2400 }
	]

	// Determine active section based on scroll position
	let activeSection = $derived(
		sections.reduce((active, section) => {
			if (scrollY >= section.offset - 100) {
				return section
			}
			return active
		}, sections[0])
	)

	function scrollToSection(section) {
		// Setting scrollY programmatically scrolls the window
		targetSection = section
		scrollY = section.offset
	}

	// Smooth scroll effect using $effect
	$effect(() => {
		if (targetSection) {
			// For smooth scrolling, you might use window.scrollTo instead
			window.scrollTo({
				top: targetSection.offset,
				behavior: 'smooth'
			})
			targetSection = null
		}
	})
</script>

<svelte:window bind:scrollY />

<nav class="section-nav">
	{#each sections as section}
		<button
			class={{ active: activeSection?.id === section.id }}
			onclick={() => scrollToSection(section)}
		>
			{section.name}
		</button>
	{/each}
</nav>

<div class="scroll-indicator">
	<div class="progress" style:height="{(scrollY / 2400) * 100}%"></div>
</div>

La naturaleza bidireccional de los bindings de scroll crea posibilidades interesantes pero también posibles trampas. Establecer scrollY directamente provoca un salto inmediato a esa posición—para un desplazamiento suave, deberías usar window.scrollTo con la opción behavior: 'smooth' en su lugar.

Monitoreo del Estado de Red con el Binding `online`

El binding online refleja navigator.onLine, proporcionando una forma reactiva de responder a los cambios de conectividad de red:

<script>
	let online = $state(true)
	let offlineQueue = $state([])
	let reconnectAttempts = $state(0)

	// React to connectivity changes
	$effect(() => {
		if (online && offlineQueue.length > 0) {
			processOfflineQueue()
		}
	})

	async function processOfflineQueue() {
		const queue = [...offlineQueue]
		offlineQueue = []

		for (const action of queue) {
			try {
				await action.execute()
			} catch (error) {
				// Re-queue failed actions
				offlineQueue = [...offlineQueue, action]
			}
		}
	}

	function queueAction(action) {
		if (online) {
			action.execute()
		} else {
			offlineQueue = [...offlineQueue, action]
		}
	}
</script>

<svelte:window bind:online />

{#if !online}
	<div class="offline-banner" role="alert">
		<span class="icon">📡</span>
		<span>You're offline. Changes will sync when connected.</span>
		{#if offlineQueue.length > 0}
			<span class="badge">{offlineQueue.length} pending</span>
		{/if}
	</div>
{/if}

El binding online proporciona una abstracción conveniente, pero recuerda que navigator.onLine tiene limitaciones. Indica si el navegador cree que tiene acceso a la red, no si esa red puede realmente llegar a tus servidores. Para un manejo robusto del modo sin conexión, combina este binding con la detección real de éxito/fallo de las solicitudes.

Soporte para Pantallas de Alta Densidad con `devicePixelRatio`

El binding devicePixelRatio habilita el renderizado adaptativo para pantallas de alta densidad:

<script>
	let devicePixelRatio = $state(1)
	let canvas

	// Reactive canvas sizing based on DPR
	$effect(() => {
		if (!canvas) return

		const rect = canvas.getBoundingClientRect()
		const ctx = canvas.getContext('2d')

		// Scale canvas for high-DPI displays
		canvas.width = rect.width * devicePixelRatio
		canvas.height = rect.height * devicePixelRatio

		ctx.scale(devicePixelRatio, devicePixelRatio)

		// Redraw content at appropriate resolution
		drawVisualization(ctx, rect.width, rect.height)
	})

	function drawVisualization(ctx, width, height) {
		// Drawing code here renders at native resolution
		ctx.fillStyle = '#3b82f6'
		ctx.fillRect(10, 10, width - 20, height - 20)
	}
</script>

<svelte:window bind:devicePixelRatio />

<div class="canvas-container">
	<canvas bind:this={canvas}></canvas>
	<p class="dpr-info">Device Pixel Ratio: {devicePixelRatio}</p>
</div>

<style>
	canvas {
		width: 100%;
		height: 300px;
	}
</style>

Ten en cuenta que el comportamiento de devicePixelRatio varía entre navegadores. Chrome actualiza este valor en respuesta a cambios en el nivel de zoom, mientras que Firefox y Safari típicamente solo reflejan la densidad de píxeles nativa de la pantalla.

El Módulo `svelte/reactivity/window`

Un Enfoque Alternativo

Svelte 5.11.0 introdujo svelte/reactivity/window, un módulo que proporciona versiones reactivas de los valores de window sin requerir el elemento <svelte:window>. Este enfoque alternativo ofrece diferentes compensaciones que vale la pena entender.

Entendiendo los Valores Reactivos de Window

El módulo exporta objetos con una propiedad current reactiva:

<script>
	import {
		innerWidth,
		innerHeight,
		outerWidth,
		outerHeight,
		scrollX,
		scrollY,
		online,
		devicePixelRatio,
		screenLeft,
		screenTop
	} from 'svelte/reactivity/window'
</script>

<div class="viewport-info">
	<p>Window size: {innerWidth.current}×{innerHeight.current}</p>
	<p>Outer size: {outerWidth.current}×{outerHeight.current}</p>
	<p>Scroll position: ({scrollX.current}, {scrollY.current})</p>
	<p>Screen position: ({screenLeft.current}, {screenTop.current})</p>
	<p>Network status: {online.current ? 'Online' : 'Offline'}</p>
	<p>Pixel ratio: {devicePixelRatio.current}</p>
</div>

screenLeft y screenTop rastrean la posición de la ventana del navegador en la pantalla y se actualizan dentro de un callback de requestAnimationFrame. Todos los valores son undefined durante el SSR.

La propiedad .current es reactiva, lo que significa que se actualiza automáticamente cuando el valor subyacente de window cambia. Estos valores reactivos funcionan perfectamente en plantillas, valores derivados y efectos.

Cuándo Usar `svelte/reactivity/window` vs `<svelte:window>`

Elige svelte/reactivity/window cuando:

Solo necesitas leer valores, no manejar eventos. El módulo proporciona valores reactivos pero no tiene capacidad de manejo de eventos.
Estás trabajando en un archivo .svelte.js o .svelte.ts. Como estos archivos no pueden contener sintaxis de plantilla, no puedes usar <svelte:window>, pero sí puedes importar desde el módulo.
Quieres compartir el estado reactivo de window entre múltiples componentes. Las exportaciones del módulo son singletons, lo que las hace ideales para escenarios de estado compartido.

// lib/window-state.svelte.js
import { innerWidth, innerHeight } from 'svelte/reactivity/window'

export function useResponsive() {
	let breakpoint = $derived(
		innerWidth.current < 640 ? 'mobile' : innerWidth.current < 1024 ? 'tablet' : 'desktop'
	)

	let isCompact = $derived(innerWidth.current < 640 || innerHeight.current < 480)

	return {
		get breakpoint() {
			return breakpoint
		},
		get isCompact() {
			return isCompact
		},
		get width() {
			return innerWidth.current
		},
		get height() {
			return innerHeight.current
		}
	}
}

Elige <svelte:window> cuando:

Necesitas manejar eventos de window. El módulo no soporta el manejo de eventos—solo <svelte:window> proporciona esa capacidad.
Necesitas bindings de scroll bidireccionales. Si bien el módulo proporciona scrollX y scrollY, estos son de solo lectura. Solo los bindings de <svelte:window> permiten el desplazamiento programático mediante asignación.
Prefieres mantener las interacciones con window explícitas en tu plantilla. El elemento hace visibles las dependencias de window en el marcado del componente.

Combinando Ambos Enfoques

A veces la solución óptima combina ambos enfoques:

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

	let lastScrollDirection = $state('none')
	let previousScrollY = 0

	// Use module for reactive values
	let isMobile = $derived(innerWidth.current < 640)

	// Use element for event handling
	function handleScroll() {
		const currentY = window.scrollY
		lastScrollDirection = currentY > previousScrollY ? 'down' : 'up'
		previousScrollY = currentY
	}
</script>

<!-- Event handling requires the element -->
<svelte:window onscroll={handleScroll} />

<header class={{ mobile: isMobile, scrolled: lastScrollDirection === 'down' }}>
	<!-- Header content -->
</header>

Consideraciones sobre el Renderizado del Lado del Servidor

Una de las características más valiosas de <svelte:window> es su seguridad en SSR. El elemento no produce ninguna salida durante el renderizado en el servidor, y sus bindings se resuelven como undefined en el servidor:

<script>
	let innerWidth = $state(undefined)
	let innerHeight = $state(undefined)

	// These will be undefined during SSR
	let isClient = $derived(innerWidth !== undefined)
</script>

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

{#if isClient}
	<div class="client-only-ui">
		Viewport: {innerWidth}×{innerHeight}
	</div>
{:else}
	<div class="placeholder">Loading viewport information...</div>
{/if}

El módulo svelte/reactivity/window sigue el mismo patrón—todos los valores .current son undefined en el servidor:

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

	// innerWidth.current is undefined during SSR
	let greeting = $derived(
		innerWidth.current === undefined
			? 'Welcome!'
			: innerWidth.current < 640
				? 'Hello, mobile user!'
				: 'Hello, desktop user!'
	)
</script>

<h1>{greeting}</h1>

Manejo de Discrepancias en la Hidratación

Un problema común ocurre cuando el contenido renderizado en el servidor no coincide con el renderizado inicial del cliente. Considera este patrón problemático:

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

	// PROBLEM: Server renders default, client renders actual
	let columns = $derived(
		innerWidth.current === undefined
			? 3 // Server default
			: Math.floor(innerWidth.current / 300)
	)
</script>

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

Si el servidor renderiza con 3 columnas pero el viewport del cliente resulta en 4 columnas, la hidratación detectará una discrepancia. Las soluciones incluyen:

Aceptar la discrepancia inicial con un estado de carga:

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

	let mounted = $state(false)

	$effect(() => {
		mounted = true
	})

	let columns = $derived(!mounted ? 3 : Math.floor((innerWidth.current ?? 900) / 300))
</script>

Usar CSS para el diseño inicial, JavaScript para la mejora progresiva:

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

	let calculatedColumns = $derived(innerWidth.current ? Math.floor(innerWidth.current / 300) : null)
</script>

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

<style>
	.grid {
		display: grid;
		/* CSS default, overridden by JS when available */
		grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
	}

	.grid[style*='--columns'] {
		grid-template-columns: repeat(var(--columns), 1fr);
	}
</style>

Patrones Avanzados y Consideraciones Arquitectónicas

Construyendo un Gestor de Estado de Window

Para aplicaciones complejas, centralizar la gestión del estado de window proporciona consistencia y reduce los listeners redundantes:

// lib/window-manager.svelte.js
import { innerWidth, innerHeight, online } from 'svelte/reactivity/window'

class WindowManager {
	// Breakpoint definitions
	breakpoints = {
		mobile: 640,
		tablet: 1024,
		desktop: 1440
	}

	get width() {
		return innerWidth.current
	}

	get height() {
		return innerHeight.current
	}

	get isOnline() {
		return online.current
	}

	get currentBreakpoint() {
		const width = this.width
		if (width === undefined) return 'unknown'
		if (width < this.breakpoints.mobile) return 'mobile'
		if (width < this.breakpoints.tablet) return 'tablet'
		if (width < this.breakpoints.desktop) return 'desktop'
		return 'wide'
	}

	get isMobile() {
		return this.currentBreakpoint === 'mobile'
	}

	get isTablet() {
		return this.currentBreakpoint === 'tablet'
	}

	get isDesktop() {
		return ['desktop', 'wide'].includes(this.currentBreakpoint)
	}

	get orientation() {
		if (this.width === undefined || this.height === undefined) {
			return 'unknown'
		}
		return this.height > this.width ? 'portrait' : 'landscape'
	}

	get aspectRatio() {
		if (this.width === undefined || this.height === undefined) {
			return undefined
		}
		return this.width / this.height
	}
}

export const windowManager = new WindowManager()

El uso en los componentes se vuelve notablemente limpio:

<script>
	import { windowManager } from '$lib/window-manager.svelte.js'
</script>

{#if windowManager.isMobile}
	<MobileLayout />
{:else if windowManager.isTablet}
	<TabletLayout />
{:else}
	<DesktopLayout />
{/if}

<footer>
	{windowManager.currentBreakpoint} | {windowManager.orientation}
</footer>

Implementando Sistemas de Atajos de Teclado

El manejo de teclado a nivel de window habilita atajos a lo largo de toda la aplicación. Un sistema bien arquitecturado previene conflictos y facilita el descubrimiento:

<script>
	import { getContext, setContext } from 'svelte'

	// Shortcut registry
	let shortcuts = $state(new Map())

	function registerShortcut(key, modifiers, handler, description) {
		const id = `${modifiers.sort().join('+')}+${key}`
		shortcuts.set(id, { key, modifiers, handler, description })

		return () => shortcuts.delete(id)
	}

	function handleKeydown(event) {
		const modifiers = []
		if (event.ctrlKey || event.metaKey) modifiers.push('ctrl')
		if (event.shiftKey) modifiers.push('shift')
		if (event.altKey) modifiers.push('alt')

		const id = `${modifiers.sort().join('+')}+${event.key.toLowerCase()}`
		const shortcut = shortcuts.get(id)

		if (shortcut) {
			event.preventDefault()
			shortcut.handler(event)
		}
	}

	// Provide context for child components
	setContext('shortcuts', { register: registerShortcut, shortcuts })

	// Built-in shortcuts
	registerShortcut('k', ['ctrl'], () => openCommandPalette(), 'Open command palette')
	registerShortcut('/', [], () => focusSearch(), 'Focus search')
	registerShortcut('escape', [], () => closeModals(), 'Close modal')
</script>

<svelte:window onkeydown={handleKeydown} />

<slot />

<!-- Optional: Shortcut help modal -->
{#if showShortcutHelp}
	<div class="shortcut-help">
		<h2>Keyboard Shortcuts</h2>
		<dl>
			{#each [...shortcuts.values()] as shortcut}
				<dt>
					{#each shortcut.modifiers as mod}
						<kbd>{mod}</kbd> +
					{/each}
					<kbd>{shortcut.key}</kbd>
				</dt>
				<dd>{shortcut.description}</dd>
			{/each}
		</dl>
	</div>
{/if}

Los componentes hijos pueden luego registrar sus propios atajos:

<script>
	import { getContext, onDestroy } from 'svelte'

	const { register } = getContext('shortcuts')

	// Register component-specific shortcuts
	const unregisterSave = register('s', ['ctrl'], handleSave, 'Save document')
	const unregisterUndo = register('z', ['ctrl'], handleUndo, 'Undo')

	onDestroy(() => {
		unregisterSave()
		unregisterUndo()
	})
</script>

Aplicando Debounce y Throttle a Eventos de Window

Algunos eventos de window se disparan con alta frecuencia, particularmente scroll y resize. Sin limitación de velocidad, los handlers pueden causar problemas de rendimiento:

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

	// Throttle scroll handler (fires at most once per frame)
	let scrollTicking = false
	function handleScroll() {
		if (!scrollTicking) {
			requestAnimationFrame(() => {
				scrollY = window.scrollY
				scrollTicking = false
			})
			scrollTicking = true
		}
	}

	// Debounce resize handler (fires after resizing stops)
	let resizeTimeout
	function handleResize() {
		clearTimeout(resizeTimeout)
		resizeTimeout = setTimeout(() => {
			innerWidth = window.innerWidth
			recalculateLayout()
		}, 150)
	}

	function recalculateLayout() {
		// Expensive layout calculations here
	}
</script>

<svelte:window onscroll={handleScroll} onresize={handleResize} />

Para los bindings de svelte:window (a diferencia de los manejadores de eventos), Svelte ya maneja las actualizaciones de manera eficiente. Los bindings utilizan el sistema de eventos nativo del navegador y se actualizan de forma reactiva—no necesitas aplicarles debounce manualmente.

Coordinando Múltiples Componentes que Dependen de Window

Cuando múltiples componentes necesitan el estado de window, evita duplicar elementos <svelte:window>. En su lugar, eleva la interacción con window a un padre compartido o usa el módulo svelte/reactivity/window:

<!-- Layout.svelte - Single source of window state -->
<script>
	let { children } = $props()
	let innerWidth = $state(0)
	let innerHeight = $state(0)
	let scrollY = $state(0)

	// Provide via context
	import { setContext } from 'svelte'

	setContext('viewport', {
		get width() {
			return innerWidth
		},
		get height() {
			return innerHeight
		},
		get scrollY() {
			return scrollY
		}
	})
</script>

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

{@render children()}

<!-- ChildComponent.svelte - Consumes via context -->
<script>
	import { getContext } from 'svelte'

	const viewport = getContext('viewport')

	// Use viewport.width, viewport.height, viewport.scrollY
</script>

Comparación con Elementos Especiales Relacionados

Svelte proporciona una familia de elementos especiales para diferentes destinos del DOM. Entender sus diferencias te ayuda a elegir la herramienta correcta:

`<svelte:window>` vs `<svelte:document>`

<svelte:document> se enlaza al documento en lugar de la ventana:

<svelte:document
	onvisibilitychange={handleVisibilityChange}
	bind:activeElement
	bind:fullscreenElement
	bind:visibilityState
/>

El documento proporciona diferentes propiedades—activeElement para el seguimiento del foco, visibilityState para la visibilidad de la pestaña y fullscreenElement para la detección de pantalla completa. Algunos eventos como visibilitychange se disparan en el documento en lugar de en la ventana.

`<svelte:window>` vs `<svelte:body>`

<svelte:body> se adjunta a document.body:

<svelte:body onmouseenter={handleMouseEnter} onmouseleave={handleMouseLeave} />

Eventos como mouseenter y mouseleave no se propagan al window, lo que hace necesario <svelte:body> para detectar cuándo el mouse entra o sale del área del viewport.

Errores Comunes y Cómo Evitarlos

1. Acceder a Window en la Fase Incorrecta del Ciclo de Vida

Problema: Acceder al objeto global window directamente en el ámbito del script de nivel superior o durante la inicialización del componente.

Consecuencias: El objeto window es una API específica del navegador. Las aplicaciones SvelteKit generalmente se ejecutan primero en el servidor (SSR) donde window no existe. Acceder a él directamente hace que la aplicación falle con errores "window is not defined" durante el renderizado en el servidor.

Cómo Evitarlo: Usa los bindings de <svelte:window> que son automáticamente seguros para SSR, o envuelve el acceso manual a window dentro de $effect (que solo se ejecuta en el navegador).

<script>
	// WRONG: window doesn't exist during SSR
	let currentWidth = window.innerWidth

	// CORRECT: use binding or check for existence
	let innerWidth = $state(0)

	// Or check manually
	$effect(() => {
		if (typeof window !== 'undefined') {
			// Safe to access window
		}
	})
</script>

<svelte:window bind:innerWidth />

2. Crear Múltiples Listeners para el Mismo Evento

Problema: Colocar <svelte:window> dentro de un componente que se instancia múltiples veces, como dentro de un bloque {#each}.

Consecuencias: Cada instancia del componente adjunta su propio event listener al objeto window global. Si renderizas una lista de 100 elementos, inadvertidamente creas 100 listeners de scroll separados. Esto desperdicia memoria y degrada el rendimiento, ya que el navegador debe ejecutar 100 funciones por cada evento.

Cómo Evitarlo: Eleva la interacción con window a un único componente padre (como un layout o contenedor de lista) y pasa los datos relevantes a los hijos mediante props o contexto.

<!-- WRONG: Each instance creates redundant listeners -->
{#each items as item}
	<ItemComponent />
{/each}

<!-- Where ItemComponent has: -->
<svelte:window onscroll={handleScroll} />

3. Operaciones Costosas en Handlers de Alta Frecuencia

Problema: Realizar cálculos pesados, consultas al DOM (document.querySelector) o lecturas que desencadenan layout (offsetWidth) dentro de handlers para eventos de alta frecuencia como scroll, resize o mousemove.

Consecuencias: Estos eventos pueden dispararse decenas de veces por segundo (hasta la tasa de refresco de pantalla). Las operaciones pesadas bloquean el hilo principal, causando "jank" (fotogramas perdidos), interfaz no responsiva y alto uso de CPU.

Cómo Evitarlo: Usa throttling para limitar la frecuencia de ejecución, o requestAnimationFrame para sincronizar las actualizaciones con el ciclo de renderizado del navegador.

<script>
	// WRONG: DOM measurement on every scroll event
	function handleScroll() {
		const elements = document.querySelectorAll('.item')
		elements.forEach((el) => {
			// Expensive operations
		})
	}

	// CORRECT: Throttle and cache
	let items = []
	let ticking = false

	function handleScroll() {
		if (!ticking) {
			requestAnimationFrame(() => {
				// Process cached items
				ticking = false
			})
			ticking = true
		}
	}
</script>

<svelte:window onscroll={handleScroll} />

4. Olvidar las Implicaciones de SSR en Valores Derivados

Problema: Crear estado derivado que realiza cálculos sobre bindings de window sin manejar el estado inicial undefined durante SSR.

Consecuencias: Durante el Server-Side Rendering, los bindings de window como innerWidth son undefined. Las operaciones matemáticas sobre undefined (como undefined / 200) resultan en NaN o lanzan errores. Esto puede hacer que el renderizado en el servidor falle o produzca HTML inválido con valores NaN.

Cómo Evitarlo: Siempre proporciona un valor de fallback o verifica explícitamente undefined en tu lógica derivada para garantizar un estado predeterminado válido para el HTML renderizado en el servidor.

<script>
	let innerWidth = $state(undefined)

	// WRONG: Fails when innerWidth is undefined
	let columnCount = $derived(Math.floor(innerWidth / 200))

	// CORRECT: Handle undefined case
	let columnCount = $derived(innerWidth !== undefined ? Math.floor(innerWidth / 200) : 3)
</script>

<svelte:window bind:innerWidth />

Mejores Prácticas de Rendimiento

1. Minimizar los Bindings Reactivos

Cada propiedad que vinculas a <svelte:window> crea un event listener interno y una sincronización de estado reactivo. Vincular propiedades que no usas agrega una sobrecarga innecesaria.

Mejor Práctica: Vincula únicamente las propiedades específicas que requiere tu lógica.

<!-- WRONG: Over-binding creates unnecessary listeners and updates -->
<svelte:window
  bind:innerWidth
  bind:innerHeight
  bind:scrollX
  bind:scrollY
/>

<!-- CORRECT: Bind only what is needed -->
<svelte:window bind:scrollY />

2. Preferir CSS para la Responsividad Visual

La responsividad basada en JavaScript (usando innerWidth) obliga al navegador a ejecutar código, recalcular estilos y repintar en cada evento de resize. Esto es significativamente más lento que las media queries nativas de CSS, que están optimizadas por el motor del navegador.

Mejor Práctica: Usa media queries de CSS para los cambios de layout. Reserva los bindings de <svelte:window> para la lógica que no puede expresarse en CSS (como el renderizado condicional de componentes pesados o el dimensionado de canvas).

<style>
	/* FAST: Handled by the browser's layout engine */
	.sidebar {
		width: 100%;
	}
	@media (min-width: 768px) {
		.sidebar {
			width: 300px;
		}
	}
</style>

3. Usar Estado Derivado para Cálculos de Window

Evita usar $effect para actualizar manualmente el estado basándote en cambios de window. Esto desencadena un segundo paso de renderizado. En su lugar, usa $derived para calcular valores derivados de los bindings de window. La reactividad de grano fino de Svelte garantiza que estos solo se recalculen cuando cambien las dependencias específicas.

Mejor Práctica: Calcula los valores dependientes de window usando $derived.

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

	// EFFICIENT: Calculates lazily and only when dependencies change
	let viewport = $derived({
		width: innerWidth,
		height: innerHeight,
		aspectRatio: innerWidth / innerHeight,
		isLandscape: innerWidth > innerHeight,
		breakpoint: innerWidth < 640 ? 'mobile' : 'desktop'
	})
</script>

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

Este enfoque es más eficiente que usar $effect porque aprovecha el sistema de reactividad de Svelte para calcular valores solo cuando cambian las dependencias, sin desencadenar ciclos de renderizado adicionales.

Conclusión

El elemento especial <svelte:window> ejemplifica la filosofía de Svelte de hacer que las tareas comunes sean trivialmente sencillas mientras mantiene posibles los casos de uso avanzados. Al abstraer la complejidad de la gestión del ciclo de vida de los event listeners y la seguridad SSR, te permite concentrarte en lo que importa: crear aplicaciones responsivas e interactivas que respondan con elegancia al entorno del usuario.

La introducción de svelte/reactivity/window en Svelte 5.11 proporciona un enfoque complementario para escenarios donde necesitas valores reactivos de window sin la sintaxis de binding basada en plantillas.

A medida que construyas componentes conscientes de window, recuerda estos principios arquitectónicos: centraliza el estado de window cuando múltiples componentes lo necesiten, elige la estrategia de limitación de frecuencia adecuada para eventos de alta frecuencia, diseña pensando en SSR desde el principio, y prefiere CSS para la responsividad puramente visual.

Los patrones explorados aquí —gestores centralizados de window, sistemas de atajos de teclado y gestión coordinada de estado— demuestran que la interacción con window no es solo una cuestión de mecánica técnica, sino de arquitectura reflexiva.

En conjunto, estas herramientas y patrones permiten construir aplicaciones que no solo son funcionales, sino que están optimizadas para los diversos entornos donde los usuarios las experimentan. La ventana del navegador es el marco de tu aplicación — <svelte:window> te da las herramientas para que ese marco sea un participante activo en la experiencia de usuario.

Puntos Clave

<svelte:window> proporciona manejo declarativo y seguro para SSR de eventos de window con limpieza automática, eliminando la necesidad de gestión manual de listeners y previniendo fugas de memoria
Los handlers de eventos soportan eventos DOM estándar (onkeydown, onscroll, onresize) con manejo opcional de la fase de captura usando el sufijo capture (p. ej., onkeydowncapture)
Los bindings reactivos habilitan el flujo de datos bidireccional con propiedades de solo lectura (innerWidth, innerHeight, outerWidth, outerHeight, online, devicePixelRatio) y propiedades de scroll escribibles (scrollX, scrollY)
El módulo svelte/reactivity/window ofrece una alternativa para leer valores de window en archivos .svelte.js o compartir estado entre componentes, pero carece de manejo de eventos y capacidades de scroll programático
La seguridad SSR está incorporada - todos los bindings se resuelven como undefined en el servidor, lo que requiere valores de fallback en la lógica derivada para evitar desajustes de hidratación
La optimización del rendimiento requiere throttling de los eventos de alta frecuencia (scroll, resize, mousemove) usando requestAnimationFrame o debouncing, y preferir las media queries de CSS sobre JavaScript para la responsividad visual
Los patrones arquitectónicos incluyen la gestión centralizada de estado mediante contexto o módulos reactivos, gestores jerárquicos de window para lógica de breakpoints, y registros de atajos de teclado con manejo de prioridades
Los errores comunes involucran el acceso en SSR, crear listeners redundantes en bucles, operaciones costosas en handlers de eventos, y olvidar manejar undefined en cálculos derivados

Ver También

Documentación Oficial de Svelte 5 - <svelte:window>
MDN Web Docs - Interfaz Window
<svelte:document> - Elemento especial similar para eventos a nivel de document
<svelte:body> - Manejo de eventos a nivel de body para diferentes escenarios de propagación de eventos
Svelte 5 Runes - $derived - Cálculos reactivos basados en el estado de window
Server-Side Rendering (SSR) en SvelteKit - Comprender las restricciones de SSR con las APIs del navegador
Diseño Responsivo con Media Queries de CSS - Cuándo preferir CSS sobre la responsividad con JavaScript