Gestión de Estado a Través de los Límites de Componentes en Svelte 5

Navegando los Límites del Estado

La gestión de estado es el corazón palpitante de cualquier aplicación reactiva. Determina cómo fluyen los datos a través de tus componentes, cómo responde tu UI a los cambios y, en última instancia, qué tan mantenible y eficiente se vuelve tu aplicación a medida que escala. Svelte 5 ha reimaginado fundamentalmente la gestión de estado con la introducción de los runes, proporcionando a los desarrolladores un conjunto de herramientas más explícito, predecible y poderoso para gestionar el estado reactivo.

En Svelte 4 y versiones anteriores, los desarrolladores dependían de una combinación de declaraciones reactivas ($:), stores de svelte/store y la API de Contexto para gestionar el estado a través de diferentes ámbitos. Si bien estas herramientas eran efectivas, creaban un modelo mental fragmentado. El estado reactivo dentro de los componentes funcionaba de manera diferente al estado reactivo fuera de los componentes, y compartir estado requería comprender múltiples paradigmas.

Los runes de Svelte 5 unifican esta experiencia. El rune $state funciona de manera idéntica tanto dentro de un componente como dentro de un módulo .svelte.js. El rune $derived reemplaza tanto las declaraciones reactivas como los stores derivados. Esta consistencia significa que puedes enfocarte en entender un único conjunto de patrones que se aplican en todas partes, en lugar de aprender diferentes enfoques para diferentes contextos.

Sin embargo, este sistema unificado introduce nuevas preguntas: ¿Cuándo debería vivir el estado dentro de un único componente? ¿Cuándo debería elevarse a un módulo compartido? ¿Cuándo se vuelve necesaria la API de Contexto? ¿Y cuándo podrías querer salir de la reactividad profunda con $state.raw para construir stores personalizados de mayor rendimiento?

Este artículo te guiará a través de estas decisiones de manera sistemática. Construiremos un modelo mental integral para los límites del estado, exploraremos las compensaciones de cada enfoque y desarrollaremos patrones prácticos que puedes aplicar de inmediato en tus aplicaciones Svelte 5. Al final, entenderás no solo cómo usar cada enfoque de gestión de estado, sino por qué y cuándo cada uno se convierte en la opción óptima.

Entendiendo los Límites del Estado: Un Modelo Mental

Antes de profundizar en APIs específicas, establezcamos un marco conceptual para pensar en los límites del estado. Cada pieza de estado en tu aplicación existe en algún punto de un espectro que va desde "completamente local" hasta "compartido globalmente". Entender dónde pertenece una pieza de estado particular en este espectro es el primer paso para elegir el enfoque de gestión adecuado.

El Espectro de Alcance del Estado

Considera el estado como existente en cuatro ámbitos principales, cada uno con características distintas:

Estado Local del Componente representa datos que están intrínsecamente ligados a una única instancia de componente. Piensa en los valores de un formulario durante su edición, el estado de la UI como si un menú desplegable está abierto, o cálculos temporales que solo importan dentro del ciclo de vida de ese componente. Este estado nace cuando el componente se monta y muere cuando se desmonta. No tiene significado fuera de su componente.

Estado Compartido del Subárbol engloba datos que necesitan fluir a través de una porción de tu árbol de componentes sin tener que pasarse explícitamente a través de cada componente intermedio. Considera un objeto de tema al que toda una sección de funcionalidad necesita acceder, o preferencias de usuario que requieren múltiples componentes profundamente anidados. Este estado tiene significado más allá de un único componente, pero no necesita estar disponible globalmente.

Estado a Nivel de Módulo se refiere a datos singleton que persisten durante toda la vida de tu aplicación (o hasta que el módulo se recarga). Los objetos de configuración, cachés o el estado de toda la aplicación que cualquier componente pueda necesitar caen en esta categoría. En una aplicación puramente del lado del cliente, esto es efectivamente un estado global.

Estado con Alcance de Solicitud (particularmente relevante para aplicaciones SvelteKit) es el estado que debe estar aislado por solicitud durante el renderizado del lado del servidor. Esto es crucial en contextos SSR donde un único proceso del servidor maneja múltiples usuarios: el estado que se filtra entre solicitudes puede exponer los datos de un usuario a otro.

Comprender estos ámbitos te ayuda a tomar decisiones informadas sobre dónde debe vivir el estado. Exploremos cada enfoque en detalle.

Estado Local del Componente con `$state`

La forma más común y directa de gestión de estado es el estado local del componente usando el rune $state. Este es el estado que vive completamente dentro de una única instancia de componente, se crea cuando el componente se inicializa y se limpia cuando el componente es destruido.

Estado Local Básico

Cuando el estado es puramente local a un componente, $state proporciona un mecanismo simple y poderoso para crear valores reactivos:

<script>
	// Simple reactive counter - state lives entirely within this component
	let count = $state(0)

	// Complex reactive object - Svelte creates a deep reactive proxy
	let user = $state({
		name: '',
		email: '',
		preferences: {
			theme: 'light',
			notifications: true
		}
	})

	function incrementCount() {
		count++
	}

	function updateTheme(newTheme) {
		// Deep reactivity means this update triggers UI updates
		user.preferences.theme = newTheme
	}
</script>

<div>
	<p>Count: {count}</p>
	<button onclick={incrementCount}>Increment</button>

	<input bind:value={user.name} placeholder="Name" />
	<input bind:value={user.email} placeholder="Email" />

	<select bind:value={user.preferences.theme}>
		<option value="light">Light</option>
		<option value="dark">Dark</option>
	</select>
</div>

Este ejemplo demuestra dos características clave de $state. Primero, los primitivos como los números se vuelven reactivos: cualquier asignación dispara actualizaciones en la UI. Segundo, los objetos y arreglos se convierten en proxies profundamente reactivos, lo que significa que los cambios en cualquier nivel de anidamiento se propagan automáticamente a la UI.

Cuándo el Estado Local Es la Elección Correcta

El estado local es apropiado cuando se cumplen todas las siguientes condiciones:

El estado solo tiene significado dentro del contexto de un único componente. Los errores de validación de un formulario, por ejemplo, no tienen significado fuera del componente de formulario que los genera. El ciclo de vida del estado está ligado al ciclo de vida del componente: cuando el componente es destruido, el estado debe dejar de existir. Además, ningún otro componente necesita leer o modificar este estado directamente.

Considera este ejemplo más completo de un componente de entrada de búsqueda con estado local:

<script>
	// All of this state is purely local - no other component cares about it
	let query = $state('')
	let isFocused = $state(false)
	let suggestions = $state([])
	let selectedIndex = $state(-1)
	let isLoading = $state(false)

	// Derived state - computed from local state
	let hasSuggestions = $derived(suggestions.length > 0)
	let selectedSuggestion = $derived(selectedIndex >= 0 ? suggestions[selectedIndex] : null)

	async function fetchSuggestions(searchQuery) {
		if (searchQuery.length < 2) {
			suggestions = []
			return
		}

		isLoading = true
		try {
			const response = await fetch(`/api/suggestions?q=${encodeURIComponent(searchQuery)}`)
			suggestions = await response.json()
			selectedIndex = -1
		} finally {
			isLoading = false
		}
	}

	function handleKeydown(event) {
		if (!hasSuggestions) return

		switch (event.key) {
			case 'ArrowDown':
				event.preventDefault()
				selectedIndex = Math.min(selectedIndex + 1, suggestions.length - 1)
				break
			case 'ArrowUp':
				event.preventDefault()
				selectedIndex = Math.max(selectedIndex - 1, -1)
				break
			case 'Enter':
				if (selectedSuggestion) {
					event.preventDefault()
					query = selectedSuggestion.text
					suggestions = []
				}
				break
			case 'Escape':
				suggestions = []
				selectedIndex = -1
				break
		}
	}

	// Effect to fetch suggestions when query changes
	$effect(() => {
		const currentQuery = query
		fetchSuggestions(currentQuery)
	})
</script>

<div class="search-container">
	<input
		type="text"
		bind:value={query}
		onfocus={() => (isFocused = true)}
		onblur={() => (isFocused = false)}
		onkeydown={handleKeydown}
		placeholder="Search..."
		aria-expanded={hasSuggestions}
		aria-autocomplete="list"
	/>

	{#if isLoading}
		<span class="loading-indicator">Searching...</span>
	{/if}

	{#if hasSuggestions && isFocused}
		<ul class="suggestions" role="listbox">
			{#each suggestions as suggestion, index}
				<li
					role="option"
					aria-selected={index === selectedIndex}
					class:selected={index === selectedIndex}
					onclick={() => {
						query = suggestion.text
						suggestions = []
					}}
				>
					{suggestion.text}
				</li>
			{/each}
		</ul>
	{/if}
</div>

<style>
	.search-container {
		position: relative;
		width: 100%;
		max-width: 400px;
	}

	.suggestions {
		position: absolute;
		top: 100%;
		left: 0;
		right: 0;
		background: white;
		border: 1px solid #ccc;
		border-radius: 4px;
		margin-top: 4px;
		padding: 0;
		list-style: none;
		box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
	}

	.suggestions li {
		padding: 8px 12px;
		cursor: pointer;
	}

	.suggestions li:hover,
	.suggestions li.selected {
		background: #f0f0f0;
	}

	.loading-indicator {
		position: absolute;
		right: 10px;
		top: 50%;
		transform: translateY(-50%);
		font-size: 0.8em;
		color: #666;
	}
</style>

Cada pieza de estado en este componente es intrínsecamente local. Los valores query, suggestions, selectedIndex, isFocused e isLoading no tienen significado fuera de este componente. Otros componentes podrían querer conocer el resultado final de la búsqueda, pero eso se comunicaría a través de eventos o props, no compartiendo el estado interno.

El Error de la Elevación Prematura del Estado

Un anti-patrón común es elevar el estado a un ámbito superior "por si acaso" podría ser necesario en otro lugar más adelante. Esto genera varios problemas: aumenta el acoplamiento entre componentes, hace que la refactorización sea más difícil y puede provocar problemas de rendimiento a medida que más componentes reaccionan a cambios de estado que en realidad no les importan.

Mantén el estado tan local como sea posible hasta que tengas una razón concreta para compartirlo. Si más adelante descubres que múltiples componentes necesitan acceso al mismo estado, puedes elevarlo en ese momento. Este enfoque sigue el principio de mínimo privilegio: los componentes solo deberían tener acceso al estado que realmente necesitan.

Compartiendo Estado Entre Módulos con Archivos `.svelte.js`

Cuando el estado necesita compartirse entre componentes pero no requiere los beneficios de alcance del contexto, el estado a nivel de módulo en archivos .svelte.js o .svelte.ts proporciona una solución elegante. Este enfoque crea un estado singleton que persiste durante toda la vida de tu aplicación.

Entendiendo los Archivos `.svelte.js`

Svelte 5 introduce una extensión de archivo especial—.svelte.js (o .svelte.ts para TypeScript)—que te permite usar runes fuera de los archivos de componentes. Esto te permite crear lógica reactiva reutilizable y módulos de estado compartido.

// file: counter.svelte.js

// This creates module-level reactive state - it's a singleton
// shared by all components that import this module
export const counter = $state({
	count: 0
})

export function increment() {
	counter.count++
}

export function decrement() {
	counter.count--
}

export function reset() {
	counter.count = 0
}

Cualquier componente que importe desde este módulo compartirá el mismo estado reactivo:

<!-- ComponentA.svelte -->
<script>
	import { counter, increment } from './counter.svelte.js'
</script>

<p>Count: {counter.count}</p>
<button onclick={increment}>Increment</button>

<!-- ComponentB.svelte -->
<script>
	import { counter, decrement } from './counter.svelte.js'
</script>

<p>Current value: {counter.count}</p>
<button onclick={decrement}>Decrement</button>

Ambos componentes ven el mismo objeto counter, y los cambios realizados en un componente se reflejan inmediatamente en el otro.

La Restricción Crítica de Exportación

Hay una limitación importante que debes entender al trabajar con estado a nivel de módulo: no puedes exportar directamente una variable de estado reasignable. Esta limitación existe debido a cómo el compilador de Svelte transforma el código basado en runes.

Cuando escribes let count = $state(0), el compilador lo transforma en algo como:

// Conceptual transformation (simplified)
let count = $.state(0)

// When you read count:
$.get(count)

// When you write count:
$.set(count, newValue)

Esta transformación ocurre por archivo. Si exportas count directamente y otro archivo lo importa, ese otro archivo no sabe que debe usar $.get() y $.set()—simplemente ve un objeto de señal sin procesar en lugar del valor reactivo.

Esto es lo que no funciona:

// file: broken.svelte.js
// ❌ This will NOT work as expected
export let count = $state(0)

export function increment() {
	count++ // This works internally
}

Cuando otro archivo importa count, obtiene el objeto de señal interno, no el valor numérico reactivo. Acceder a él te daría un objeto en lugar de un número.

Hay dos patrones que sí funcionan:

Patrón 1: Exportar un objeto con propiedades reactivas

// file: counter.svelte.js
// ✅ This works - we're not reassigning counter, just its properties
export const counter = $state({
	count: 0
})

export function increment() {
	counter.count++ // Updating a property, not reassigning counter
}

Patrón 2: Exportar funciones de acceso

// file: counter.svelte.js
// ✅ This also works - state is private, accessed via functions
let count = $state(0)

export function getCount() {
	return count
}

export function setCount(value) {
	count = value
}

export function increment() {
	count++
}

El primer patrón generalmente es más ergonómico para la mayoría de los casos de uso. El segundo patrón proporciona mayor encapsulamiento y es útil cuando quieres controlar exactamente cómo puede modificarse el estado.

Construyendo un Módulo de Estado Compartido Completo

Construyamos un ejemplo más realista: un carrito de compras al que múltiples componentes necesitan acceder:

// file: cart.svelte.js

// The cart state - a singleton shared across the application
export const cart = $state({
	items: [],
	isOpen: false
})

// Derived values - these are also reactive
export function getItemCount() {
	return cart.items.reduce((sum, item) => sum + item.quantity, 0)
}

export function getSubtotal() {
	return cart.items.reduce((sum, item) => sum + item.price * item.quantity, 0)
}

export function getTax(rate = 0.08) {
	return getSubtotal() * rate
}

export function getTotal(taxRate = 0.08) {
	return getSubtotal() + getTax(taxRate)
}

// Actions to modify cart state
export function addItem(product, quantity = 1) {
	const existingItem = cart.items.find((item) => item.id === product.id)

	if (existingItem) {
		existingItem.quantity += quantity
	} else {
		cart.items.push({
			id: product.id,
			name: product.name,
			price: product.price,
			image: product.image,
			quantity
		})
	}
}

export function removeItem(productId) {
	const index = cart.items.findIndex((item) => item.id === productId)
	if (index !== -1) {
		cart.items.splice(index, 1)
	}
}

export function updateQuantity(productId, quantity) {
	const item = cart.items.find((item) => item.id === productId)
	if (item) {
		if (quantity <= 0) {
			removeItem(productId)
		} else {
			item.quantity = quantity
		}
	}
}

export function clearCart() {
	cart.items = []
}

export function toggleCart() {
	cart.isOpen = !cart.isOpen
}

export function openCart() {
	cart.isOpen = true
}

export function closeCart() {
	cart.isOpen = false
}

Ahora múltiples componentes pueden interactuar con el mismo carrito:

<!-- CartIcon.svelte - Shows cart icon with item count in header -->
<script>
	import { cart, getItemCount, toggleCart } from './cart.svelte.js'

	// Using $derived to create a reactive binding to the function result
	let itemCount = $derived(getItemCount())
</script>

<button class="cart-icon" onclick={toggleCart} aria-label="Shopping cart with {itemCount} items">
	<svg><!-- cart icon --></svg>
	{#if itemCount > 0}
		<span class="badge">{itemCount}</span>
	{/if}
</button>

<!-- ProductCard.svelte - Each product can add itself to cart -->
<script>
	import { addItem, openCart } from './cart.svelte.js'

	let { product } = $props()

	function handleAddToCart() {
		addItem(product)
		openCart()
	}
</script>

<article class="product-card">
	<img src={product.image} alt={product.name} />
	<h3>{product.name}</h3>
	<p class="price">${product.price.toFixed(2)}</p>
	<button onclick={handleAddToCart}>Add to Cart</button>
</article>

<!-- CartDrawer.svelte - The sliding cart panel -->
<script>
	import {
		cart,
		updateQuantity,
		removeItem,
		getSubtotal,
		getTax,
		getTotal,
		closeCart
	} from './cart.svelte.js'

	let subtotal = $derived(getSubtotal())
	let tax = $derived(getTax())
	let total = $derived(getTotal())
</script>

<aside class="cart-drawer" class:open={cart.isOpen}>
	<header>
		<h2>Your Cart</h2>
		<button onclick={closeCart} aria-label="Close cart">×</button>
	</header>

	{#if cart.items.length === 0}
		<p class="empty-message">Your cart is empty</p>
	{:else}
		<ul class="cart-items">
			{#each cart.items as item (item.id)}
				<li class="cart-item">
					<img src={item.image} alt={item.name} />
					<div class="item-details">
						<h4>{item.name}</h4>
						<p>${item.price.toFixed(2)} each</p>
					</div>
					<div class="quantity-controls">
						<button onclick={() => updateQuantity(item.id, item.quantity - 1)}> − </button>
						<span>{item.quantity}</span>
						<button onclick={() => updateQuantity(item.id, item.quantity + 1)}> + </button>
					</div>
					<button
						class="remove-btn"
						onclick={() => removeItem(item.id)}
						aria-label="Remove {item.name} from cart"
					>
						×
					</button>
				</li>
			{/each}
		</ul>

		<footer class="cart-summary">
			<div class="summary-line">
				<span>Subtotal</span>
				<span>${subtotal.toFixed(2)}</span>
			</div>
			<div class="summary-line">
				<span>Tax</span>
				<span>${tax.toFixed(2)}</span>
			</div>
			<div class="summary-line total">
				<span>Total</span>
				<span>${total.toFixed(2)}</span>
			</div>
			<button class="checkout-btn">Proceed to Checkout</button>
		</footer>
	{/if}
</aside>

Este patrón funciona de manera excelente para aplicaciones del lado del cliente donde quieres un estado singleton real. Todos los componentes comparten exactamente la misma instancia del carrito, y los cambios en cualquier lugar se propagan inmediatamente en todas partes.

Cuándo el Estado a Nivel de Módulo Es Apropiado

El estado a nivel de módulo es ideal cuando el estado representa un singleton verdaderamente global para toda la aplicación que no necesita aislamiento por solicitud. Los ejemplos incluyen el estado de autenticación de usuario en aplicaciones del lado del cliente, la configuración de la aplicación que no cambia por solicitud, cachés para cálculos costosos y flags de características o configuraciones de pruebas A/B.

Sin embargo, el estado a nivel de módulo tiene una limitación crítica que debemos abordar: es peligroso en contextos de renderizado del lado del servidor.

La Trampa del Renderizado del Lado del Servidor

Cuando tu aplicación usa renderizado del lado del servidor (SSR), el estado a nivel de módulo se convierte en una vulnerabilidad de seguridad potencial. He aquí por qué: en el servidor, un único proceso de Node.js maneja solicitudes de múltiples usuarios. El estado a nivel de módulo es compartido entre todas esas solicitudes.

Considera este patrón peligroso:

// file: user.svelte.js
// ⚠️ DANGEROUS in SSR contexts!
export const currentUser = $state({
	id: null,
	name: null,
	email: null,
	isAuthenticated: false
})

export function setUser(userData) {
	currentUser.id = userData.id
	currentUser.name = userData.name
	currentUser.email = userData.email
	currentUser.isAuthenticated = true
}

export function clearUser() {
	currentUser.id = null
	currentUser.name = null
	currentUser.email = null
	currentUser.isAuthenticated = false
}

Si Alice inicia sesión, el servidor podría renderizar su panel y establecer sus datos de usuario en currentUser. Si la solicitud de Bob llega antes de que se complete la respuesta de Alice, ¡Bob podría ver los datos de Alice! Esto es una grave vulnerabilidad de seguridad.

Aquí es donde la API de Contexto se vuelve esencial.

La API de Contexto: Estado con Alcance por Solicitud y por Subárbol

La API de Contexto de Svelte resuelve el problema de aislamiento de estado en SSR y proporciona un mecanismo para compartir estado dentro de un subárbol de componentes sin necesidad de prop drilling. El contexto tiene alcance en el árbol de componentes: cada instancia de componente que establece un contexto crea una "burbuja" aislada a la que pueden acceder sus descendientes.

Entendiendo los Fundamentos del Contexto

El contexto funciona a través de dos funciones principales: setContext establece un valor al que los descendientes pueden acceder, y getContext recupera ese valor. El contexto está asociado a la instancia del componente que lo establece, lo que significa que distintas instancias del mismo componente pueden tener valores de contexto diferentes.

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

	// Create reactive state that will be shared via context
	let theme = $state({
		mode: 'light',
		primaryColor: '#007bff',
		fontFamily: 'Inter, sans-serif'
	})

	// Make it available to descendants
	setContext('theme', theme)

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

<div class="app" data-theme={theme.mode}>
	<button onclick={toggleMode}>
		Switch to {theme.mode === 'light' ? 'dark' : 'light'} mode
	</button>
	<Child />
</div>

<!-- Child.svelte -->
<script>
	import { getContext } from 'svelte'
	import GrandChild from './GrandChild.svelte'

	// Retrieve the theme from parent's context
	const theme = getContext('theme')
</script>

<!-- No need to pass theme as prop to GrandChild -->
<div class="child" style="font-family: {theme.fontFamily}">
	<p>Current mode: {theme.mode}</p>
	<GrandChild />
</div>

<!-- GrandChild.svelte -->
<script>
	import { getContext } from 'svelte'

	// Can access the same context from any depth
	const theme = getContext('theme')
</script>

<div class="grandchild" style="background: {theme.mode === 'dark' ? '#333' : '#fff'}">
	<p style="color: {theme.primaryColor}">Styled by context!</p>
</div>

Contexto Reactivo con `$state`

Cuando pasas un objeto $state a través del contexto, la reactividad se preserva. Los cambios en el objeto de estado en el componente padre se propagan automáticamente a todos los descendientes que lo consumen. Esto se debe a que $state crea un objeto proxy, y el contexto simplemente pasa una referencia a ese mismo proxy.

Sin embargo, hay una advertencia importante: si reasignas la variable de estado completa en el padre, "rompes el vínculo": los descendientes seguirán teniendo una referencia al objeto anterior.

<!-- Parent.svelte -->
<script>
	import { setContext } from 'svelte'

	let user = $state({
		name: 'Alice',
		preferences: { theme: 'light' }
	})

	setContext('user', user)

	// ✅ This works - updating properties maintains the reference
	function updateTheme(newTheme) {
		user.preferences.theme = newTheme
	}

	// ❌ This breaks reactivity for context consumers!
	function resetUser() {
		user = { name: 'Guest', preferences: { theme: 'light' } }
		// Descendants still have reference to the OLD object
	}

	// ✅ Instead, update properties individually
	function resetUserCorrectly() {
		user.name = 'Guest'
		user.preferences.theme = 'light'
	}
</script>

Svelte te advertirá si reasignas un valor de contexto, ayudándote a evitar este error común.

Contexto con Seguridad de Tipos Mediante Funciones Auxiliares

Para proyectos de TypeScript (y para una mejor experiencia de desarrollo en general), es una buena práctica envolver setContext y getContext en funciones auxiliares. Esto garantiza la seguridad de tipos y elimina la necesidad de gestionar manualmente claves de tipo string o symbol a lo largo de tu aplicación:

// file: contexts/user.ts
import { setContext, getContext } from 'svelte'

interface User {
	id: string
	name: string
	email: string
	role: 'admin' | 'user' | 'guest'
	preferences: {
		theme: 'light' | 'dark' | 'system'
		language: string
		notifications: boolean
	}
}

// Use a symbol to avoid key collisions
const USER_KEY = Symbol('USER')

export function setUserContext(user: User) {
	setContext(USER_KEY, user)
}

export function getUserContext() {
	return getContext<User>(USER_KEY)
}

<!-- App.svelte -->
<script lang="ts">
	import { setUserContext } from './contexts/user'

	let user = $state({
		id: 'user-123',
		name: 'Alice',
		email: 'alice@example.com',
		role: 'user' as const,
		preferences: {
			theme: 'light' as const,
			language: 'en',
			notifications: true
		}
	})

	setUserContext(user)
</script>

<!-- SomeDeepComponent.svelte -->
<script lang="ts">
	import { getUserContext } from './contexts/user'

	// Fully typed - TypeScript knows the shape of user
	const user = getUserContext()
</script>

<p>Welcome, {user.name}!</p><p>Theme: {user.preferences.theme}</p>

Contexto para el Aislamiento de Solicitudes en SvelteKit

En aplicaciones SvelteKit, el contexto proporciona aislamiento de solicitudes que el estado a nivel de módulo no puede ofrecer. Cada solicitud crea un nuevo árbol de componentes, y el contexto establecido en ese árbol está aislado de otras solicitudes.

<!-- src/routes/+layout.svelte -->
<script>
	import { setContext } from 'svelte'

	let { data, children } = $props()

	// Create request-scoped user state from server data
	let user = $state(data.user ? { ...data.user } : null)

	// Each request gets its own isolated user context
	setContext('user', {
		get current() {
			return user
		},
		set current(value) {
			user = value
		},
		logout() {
			user = null
		}
	})
</script>

{@render children()}

<!-- src/routes/dashboard/+page.svelte -->
<script>
	import { getContext } from 'svelte'

	const userContext = getContext('user')

	// Safe to access - this is isolated per request
	const user = userContext.current
</script>

{#if user}
	<h1>Welcome back, {user.name}!</h1>
	<button onclick={() => userContext.logout()}>Logout</button>
{:else}
	<p>Please log in</p>
{/if}

Cuándo Usar Contexto vs Estado de Módulo

Usa contexto cuando necesites aislamiento de solicitudes para seguridad en SSR, cuando el estado solo deba ser accesible para un subárbol (no globalmente), cuando distintas partes de tu aplicación necesiten diferentes instancias del mismo "tipo" de estado, o cuando la propiedad del estado deba estar vinculada al ciclo de vida del componente.

Usa estado a nivel de módulo cuando estés construyendo una aplicación puramente del lado del cliente, cuando el estado sea verdaderamente un singleton que todos los componentes deban compartir, cuando el estado deba persistir entre navegaciones y destrucciones de componentes, o cuando necesites acceder al estado fuera de contextos de componentes (como en funciones utilitarias).

Construyendo Stores Reactivos con `$state.raw`

Mientras que $state crea proxies profundamente reactivos que rastrean automáticamente los cambios en cualquier nivel de anidamiento, este poder tiene un costo. La creación y el mantenimiento de proxies implican una sobrecarga, y para estructuras de datos grandes que no pretendes mutar en lugar, esta sobrecarga es innecesaria.

La runa $state.raw proporciona una salida de emergencia: crea estado reactivo sin el envoltorio de proxy profundo. El valor solo es reactivo en el nivel superior: reasignar el valor completo desencadena actualizaciones, pero mutar propiedades no lo hace.

Entendiendo el Comportamiento de $state.raw

Examinemos la diferencia entre $state y $state.raw:

// With $state - deep reactivity via proxies
let user = $state({
	name: 'Alice',
	settings: {
		theme: 'dark'
	}
})

// This mutation IS reactive - triggers UI updates
user.settings.theme = 'light'

// With $state.raw - shallow reactivity only
let config = $state.raw({
	apiUrl: 'https://api.example.com',
	features: {
		darkMode: true,
		analytics: false
	}
})

// This mutation is NOT reactive - no UI updates!
config.features.darkMode = false

// This reassignment IS reactive - triggers UI updates
config = {
	apiUrl: 'https://api.example.com',
	features: {
		darkMode: false,
		analytics: false
	}
}

La conclusión clave es que los valores de $state.raw deben ser reemplazados en lugar de mutados para desencadenar la reactividad.

Beneficios de Rendimiento de `$state.raw`

Para estructuras de datos grandes, evitar la creación de proxies puede proporcionar beneficios de rendimiento significativos. Considera una tabla de datos con miles de filas:

// file: dataTable.svelte.js

// ❌ With $state - each row object becomes a proxy
// Proxy creation happens for the array AND every nested object
export const tableData = $state({
	rows: [], // Could be 10,000+ rows
	sortColumn: null,
	sortDirection: 'asc',
	filters: {}
})

// ✅ With $state.raw for the data, $state for UI state
export const tableRows = $state.raw([])
export const tableUI = $state({
	sortColumn: null,
	sortDirection: 'asc',
	selectedIds: new Set(),
	filters: {}
})

export function setRows(newRows) {
	// Complete replacement - triggers reactivity
	tableRows = newRows
}

export function sortRows(column) {
	const direction =
		tableUI.sortColumn === column && tableUI.sortDirection === 'asc' ? 'desc' : 'asc'

	// Update UI state (reactive via $state)
	tableUI.sortColumn = column
	tableUI.sortDirection = direction

	// Sort and replace the raw data
	const sorted = [...tableRows].sort((a, b) => {
		const aVal = a[column]
		const bVal = b[column]
		const comparison = aVal < bVal ? -1 : aVal > bVal ? 1 : 0
		return direction === 'asc' ? comparison : -comparison
	})

	tableRows = sorted // Replacement triggers reactivity
}

Construyendo un Patrón de Store de Datos Inmutables

$state.raw es ideal para implementar patrones de datos inmutables donde siempre se crean nuevos objetos/arreglos en lugar de mutar los existentes:

// file: todoStore.svelte.js

// Raw state - we'll manage updates through immutable patterns
let todos = $state.raw([])

// Export a getter to access current state
export function getTodos() {
	return todos
}

// All modifications create new arrays/objects
export function addTodo(text) {
	const newTodo = {
		id: crypto.randomUUID(),
		text,
		completed: false,
		createdAt: new Date()
	}

	// Create new array with new item - triggers reactivity
	todos = [...todos, newTodo]
}

export function toggleTodo(id) {
	// Map creates a new array with updated item
	todos = todos.map((todo) => (todo.id === id ? { ...todo, completed: !todo.completed } : todo))
}

export function updateTodoText(id, newText) {
	todos = todos.map((todo) => (todo.id === id ? { ...todo, text: newText } : todo))
}

export function deleteTodo(id) {
	// Filter creates a new array without the deleted item
	todos = todos.filter((todo) => todo.id !== id)
}

export function clearCompleted() {
	todos = todos.filter((todo) => !todo.completed)
}

// Bulk operations
export function setTodos(newTodos) {
	todos = newTodos
}

export function reorderTodos(fromIndex, toIndex) {
	const newTodos = [...todos]
	const [moved] = newTodos.splice(fromIndex, 1)
	newTodos.splice(toIndex, 0, moved)
	todos = newTodos
}

Usando este store en un componente:

<script>
	import { getTodos, addTodo, toggleTodo, deleteTodo, clearCompleted } from './todoStore.svelte.js'

	let newTodoText = $state('')

	// Access todos via the getter - this creates a reactive dependency
	let todos = $derived(getTodos())
	let completedCount = $derived(todos.filter((t) => t.completed).length)
	let remainingCount = $derived(todos.length - completedCount)

	function handleSubmit(event) {
		event.preventDefault()
		if (newTodoText.trim()) {
			addTodo(newTodoText.trim())
			newTodoText = ''
		}
	}
</script>

<div class="todo-app">
	<form onsubmit={handleSubmit}>
		<input type="text" bind:value={newTodoText} placeholder="What needs to be done?" />
		<button type="submit">Add</button>
	</form>

	<ul class="todo-list">
		{#each todos as todo (todo.id)}
			<li class:completed={todo.completed}>
				<input type="checkbox" checked={todo.completed} onchange={() => toggleTodo(todo.id)} />
				<span>{todo.text}</span>
				<button onclick={() => deleteTodo(todo.id)}>×</button>
			</li>
		{/each}
	</ul>

	<footer>
		<span>{remainingCount} items remaining</span>
		{#if completedCount > 0}
			<button onclick={clearCompleted}>
				Clear completed ({completedCount})
			</button>
		{/if}
	</footer>
</div>

Combinando `$state.raw` con Contenedores Reactivos

Un patrón avanzado implica usar $state.raw para datos grandes mientras se los envuelve en un contenedor reactivo:

// file: hybridStore.svelte.js

// The store state - $state for the container, $state.raw for heavy data
export const store = $state({
	// Metadata is reactive - small, frequently accessed
	isLoading: false,
	error: null,
	lastUpdated: null,

	// Large dataset uses raw - only reactive on replacement
	items: $state.raw([]),

	// Pagination state
	page: 1,
	pageSize: 50,
	totalItems: 0
})

// Derived values that work with both reactive and raw state
export function getCurrentPageItems() {
	const start = (store.page - 1) * store.pageSize
	const end = start + store.pageSize
	return store.items.slice(start, end)
}

export function getTotalPages() {
	return Math.ceil(store.totalItems / store.pageSize)
}

// Actions
export async function fetchItems(page = 1) {
	store.isLoading = true
	store.error = null

	try {
		const response = await fetch(`/api/items?page=${page}&pageSize=${store.pageSize}`)
		const data = await response.json()

		// Replace raw items - triggers reactivity
		store.items = data.items
		store.totalItems = data.total
		store.page = page
		store.lastUpdated = new Date()
	} catch (error) {
		store.error = error.message
	} finally {
		store.isLoading = false
	}
}

export function updateItem(id, updates) {
	// Immutable update of the raw array
	store.items = store.items.map((item) => (item.id === id ? { ...item, ...updates } : item))
	store.lastUpdated = new Date()
}

export function removeItem(id) {
	store.items = store.items.filter((item) => item.id !== id)
	store.totalItems--
	store.lastUpdated = new Date()
}

Cuándo Usar `$state.raw` vs `$state` Regular

Usa $state.raw cuando trabajes con arreglos grandes (cientos o miles de elementos), cuando los datos provengan de fuentes externas y no vayan a ser mutados en lugar (respuestas de API, registros de base de datos), cuando quieras aplicar patrones de actualización inmutables en tu base de código, cuando estés construyendo componentes de alto rendimiento como grillas de datos o listas virtualizadas, o cuando el estado sea de solo lectura o se reemplace principalmente de forma completa.

Quédate con $state regular cuando necesites reactividad de grano fino en propiedades anidadas, cuando la estructura de datos sea lo suficientemente pequeña como para que la sobrecarga del proxy sea insignificante, cuando las actualizaciones basadas en mutaciones sean más ergonómicas para tu caso de uso, o cuando trabajes con estructuras profundamente anidadas que se actualizan frecuentemente en distintos niveles.

Construyendo un Store Personalizado Completo con `$state.raw`

Construyamos un store de datos con todas las funcionalidades que demuestre estos patrones trabajando juntos:

// file: asyncDataStore.svelte.js

/**
 * Creates an async data store with loading states, caching, and optimistic updates
 */
export function createAsyncStore(fetchFn, options = {}) {
	const {
		cacheTime = 5 * 60 * 1000, // 5 minutes
		staleTime = 30 * 1000, // 30 seconds
		retryCount = 3,
		retryDelay = 1000
	} = options

	// Store state - hybrid approach
	const state = $state({
		// Reactive metadata
		status: 'idle', // 'idle' | 'loading' | 'success' | 'error'
		error: null,
		lastFetchedAt: null,

		// Raw data - replaced on updates
		data: $state.raw(null),

		// Request management
		currentRequestId: null
	})

	// Cache management
	let cache = new Map()

	function getCacheKey(params) {
		return JSON.stringify(params)
	}

	function isStale() {
		if (!state.lastFetchedAt) return true
		return Date.now() - state.lastFetchedAt > staleTime
	}

	function isCacheValid(cacheEntry) {
		if (!cacheEntry) return false
		return Date.now() - cacheEntry.timestamp < cacheTime
	}

	async function fetchWithRetry(params, retriesLeft) {
		try {
			return await fetchFn(params)
		} catch (error) {
			if (retriesLeft > 0) {
				await new Promise((resolve) => setTimeout(resolve, retryDelay))
				return fetchWithRetry(params, retriesLeft - 1)
			}
			// TODO: throw? Or return a special error object?
			throw error
		}
	}

	// Public API
	return {
		// Reactive getters
		get status() {
			return state.status
		},
		get error() {
			return state.error
		},
		get data() {
			return state.data
		},
		get isLoading() {
			return state.status === 'loading'
		},
		get isSuccess() {
			return state.status === 'success'
		},
		get isError() {
			return state.status === 'error'
		},
		get isStale() {
			return isStale()
		},

		// Fetch data with caching
		async fetch(params = {}) {
			const cacheKey = getCacheKey(params)
			const requestId = Symbol()
			state.currentRequestId = requestId

			// Check cache first
			const cached = cache.get(cacheKey)
			if (isCacheValid(cached)) {
				state.data = cached.data
				state.status = 'success'
				state.lastFetchedAt = cached.timestamp

				// Still refetch in background if stale
				if (isStale()) {
					this.refetch(params)
				}
				return cached.data
			}

			state.status = 'loading'
			state.error = null

			try {
				const data = await fetchWithRetry(params, retryCount)

				// Only update if this is still the current request
				if (state.currentRequestId === requestId) {
					const now = Date.now()
					state.data = data
					state.status = 'success'
					state.lastFetchedAt = now

					// Update cache
					cache.set(cacheKey, { data, timestamp: now })
				}

				return data
			} catch (error) {
				if (state.currentRequestId === requestId) {
					state.error = error.message
					state.status = 'error'
				}
				// TODO: throw? Or return a special error object?
				throw error
			}
		},

		// Force refetch (bypass cache)
		async refetch(params = {}) {
			const cacheKey = getCacheKey(params)
			cache.delete(cacheKey)
			return this.fetch(params)
		},

		// Optimistic update with rollback
		async optimisticUpdate(updateFn, commitFn) {
			const previousData = state.data

			// Apply optimistic update
			state.data = updateFn(state.data)

			try {
				// Commit to server
				const result = await commitFn(state.data)

				// Update with server response if provided
				if (result !== undefined) {
					state.data = result
				}

				// Update cache
				const cacheKey = getCacheKey({})
				cache.set(cacheKey, { data: state.data, timestamp: Date.now() })

				return result
			} catch (error) {
				// Rollback on error
				state.data = previousData
				// TODO: throw? Or return a special error object?
				throw error
			}
		},

		// Manual update
		setData(newData) {
			state.data = newData
			state.lastFetchedAt = Date.now()

			const cacheKey = getCacheKey({})
			cache.set(cacheKey, { data: newData, timestamp: Date.now() })
		},

		// Clear all state
		reset() {
			state.status = 'idle'
			state.error = null
			state.data = null
			state.lastFetchedAt = null
			cache.clear()
		},

		// Invalidate cache
		invalidate() {
			cache.clear()
		}
	}
}

Usando este store:

// file: userStore.svelte.js
import { createAsyncStore } from './asyncDataStore.svelte.ts'

async function fetchUser(params) {
	const response = await fetch(`/api/users/${params.id}`)
	if (!response.ok) error('Failed to fetch user')
	return response.json()
}

export const userStore = createAsyncStore(fetchUser, {
	cacheTime: 10 * 60 * 1000, // 10 minutes
	staleTime: 60 * 1000 // 1 minute
})

<!-- UserProfile.svelte -->
<script>
	import { userStore } from './userStore.svelte.js'

	let { userId } = $props()

	// Fetch user when component mounts or userId changes
	$effect(() => {
		userStore.fetch({ id: userId })
	})

	async function handleUpdateName(newName) {
		try {
			await userStore.optimisticUpdate(
				// Optimistic update function
				(user) => ({ ...user, name: newName }),
				// Commit function
				async (updatedUser) => {
					const response = await fetch(`/api/users/${userId}`, {
						method: 'PATCH',
						headers: { 'Content-Type': 'application/json' },
						body: JSON.stringify({ name: newName })
					})
					return response.json()
				}
			)
		} catch (error) {
			alert('Failed to update name. Changes have been reverted.')
		}
	}
</script>

<div class="user-profile">
	{#if userStore.isLoading && !userStore.data}
		<div class="skeleton">Loading...</div>
	{:else if userStore.isError}
		<div class="error">
			<p>Failed to load user: {userStore.error}</p>
			<button onclick={() => userStore.refetch({ id: userId })}> Retry </button>
		</div>
	{:else if userStore.data}
		<div class="profile-card">
			<h1>{userStore.data.name}</h1>
			<p>{userStore.data.email}</p>

			<button
				onclick={() => {
					const newName = prompt('Enter new name:', userStore.data.name)
					if (newName) handleUpdateName(newName)
				}}
			>
				Edit Name
			</button>

			{#if userStore.isStale}
				<span class="stale-indicator">
					Data may be outdated
					<button onclick={() => userStore.refetch({ id: userId })}> Refresh </button>
				</span>
			{/if}
		</div>
	{/if}
</div>

Mejores Prácticas y Errores Comunes

Mejores Prácticas

Empieza de forma local, eleva cuando sea necesario. Comienza con $state local y solo pasa a estado compartido cuando tengas una necesidad concreta. La abstracción prematura genera complejidad innecesaria.

Usa contexto para el alcance de subárbol. Cuando el estado necesite fluir a través de un subárbol de componentes sin prop drilling, el contexto es la elección correcta. Proporciona aislamiento limpio y seguridad en SSR.

Elige estado de módulo para verdaderos singletons. La configuración a nivel de aplicación, los cachés y el estado de autenticación del lado del cliente funcionan bien como estado a nivel de módulo, pero solo en contextos del lado del cliente.

Prefiere exportar objetos en lugar de primitivos. Debido a la restricción de compilación del módulo, siempre exporta objetos o usa funciones getter cuando compartas estado entre módulos.

Usa $state.raw para datos grandes e inmutables. Los arreglos grandes, las respuestas de API y los datos que siguen patrones inmutables se benefician de evitar la sobrecarga del proxy.

Combina patrones de forma reflexiva. Un enfoque híbrido suele funcionar mejor: $state.raw para los datos, $state regular para el estado de la UI, contexto para el intercambio con alcance definido.

Errores Comunes

Exportar estado reasignable directamente:

// ❌ Broken - other files can't use this reactively
export let count = $state(0)

// ✅ Fixed - export an object
export const counter = $state({ count: 0 })

Reasignar valores de contexto:

<script>
	let user = $state({ name: 'Alice' })
	setContext('user', user)

	// ❌ This breaks the context link!
	function resetUser() {
		user = { name: 'Guest' }
	}

	// ✅ Update properties instead
	function resetUser() {
		user.name = 'Guest'
	}
</script>

Usar estado de módulo en contextos SSR:

// file: auth.svelte.js
// ❌ Dangerous in SSR - shared across requests!
export const currentUser = $state({ ... });

// ✅ Use context in layout instead
// See earlier section on request-scoped context

Mutar valores de $state.raw:

let items = $state.raw([])

// ❌ This mutation won't trigger updates
items.push({ id: 1 })

// ✅ Replace the entire value
items = [...items, { id: 1 }]

Olvidar que los valores desestructurados no son reactivos:

let user = $state({ name: 'Alice' })
let { name } = user

// Later...
user.name = 'Bob'
console.log(name) // Still 'Alice'!

Consideraciones de Rendimiento

La reactividad profunda tiene costos. Cada objeto anidado en $state se convierte en un proxy. Para estructuras de datos grandes, esto añade sobrecarga de memoria y una leve latencia de acceso.

$state.raw requiere reemplazo completo. Si bien evita los costos del proxy, crear nuevos objetos para cada actualización tiene sus propios costos. Para actualizaciones muy frecuentes, mide ambos enfoques.

Las búsquedas de contexto recorren el árbol. Si bien son rápidas, getContext sí realiza una búsqueda en el árbol. Para bucles internos de alto rendimiento, considera almacenar en caché la referencia al contexto.

Los valores derivados son perezosos. $derived solo se recalcula cuando se accede a él y sus dependencias han cambiado. Esto generalmente es óptimo, pero tenlo en cuenta para la depuración.

Conclusión

La gestión de estado en Svelte 5 representa una evolución significativa respecto a versiones anteriores. El sistema de runes proporciona un enfoque unificado y consistente para la reactividad que funciona de la misma manera tanto en un componente como en un archivo de módulo. Comprender cuándo utilizar cada enfoque de gestión de estado es clave para construir aplicaciones mantenibles y con buen rendimiento.

$state local debe ser tu opción predeterminada para datos específicos de componentes. El estado a nivel de módulo en archivos .svelte.js proporciona un estado singleton conveniente para aplicaciones del lado del cliente. La API de Contexto ofrece aislamiento de solicitudes para seguridad en SSR y compartición limitada a subárboles. Y $state.raw te da una vía de escape para escenarios críticos en términos de rendimiento donde no se necesita reactividad profunda.

Los patrones que hemos explorado —desde contadores simples hasta stores asíncronos con funcionalidades completas— demuestran que los primitivos de gestión de estado de Svelte 5 son lo suficientemente poderosos para manejar casos de uso sofisticados, al tiempo que permanecen lo suficientemente simples para tareas cotidianas. Al comprender las ventajas y desventajas de cada enfoque y seguir las buenas prácticas que hemos descrito, estarás equipado para tomar decisiones informadas sobre la arquitectura de estado en tus aplicaciones Svelte.

A medida que apliques estos patrones, recuerda que las decisiones de gestión de estado no son permanentes. Empieza de manera simple, mide el rendimiento cuando sea necesario y refactoriza a medida que tu comprensión de las necesidades de tu aplicación se profundice. La flexibilidad del sistema de Svelte 5 significa que puedes adaptar tu enfoque conforme los requisitos evolucionen.