El Contador Congelado

Ya aprendiste la mecánica del contexto: cómo setContext transmite datos y getContext los recibe. Viste cómo el contexto fluye a través de los árboles de componentes y cómo el ancestro más cercano tiene prioridad. Todo tiene sentido hasta que intentas construir algo real.

Creas un contador en tu proveedor, lo compartes mediante contexto y conectas un botón para incrementarlo. El botón funciona—puedes ver el contador aumentando en el proveedor. ¿Pero el componente consumidor? Está congelado. Sigue mostrando el valor original. Click tras click, nada cambia. ¿Qué está pasando?

Este es el momento en que los desarrolladores se dan cuenta de que el contexto en sí mismo no rastrea cambios. Es un mecanismo de entrega única, no un flujo de datos en vivo. El valor que reciben los consumidores es una instantánea del momento en que llamaron a getContext, y los cambios en la fuente no se propagan automáticamente.

Pero aquí están las buenas noticias: las runes de Svelte 5 resuelven esto de manera elegante. Al entender por qué el contexto simple no es reactivo y cómo $state lo corrige, podrás construir contextos que se actualicen en todas partes, de forma automática.

Esta guía construye tu comprensión de manera progresiva a través de cuatro etapas:

El Problema de la Instantánea — Por qué el contexto captura valores congelados y qué significa eso para tus datos
Los Fundamentos — Usar objetos $state para crear referencias compartidas y reactivas
La Regla de Oro — Por qué la mutación funciona y la reasignación lo rompe todo
Patrones Avanzados — Getters para valores computados y encapsulación

Al final, tendrás un modelo mental completo para el contexto reactivo que escala desde contadores simples hasta estados de aplicación complejos.

El Espacio del Problema: Por Qué el Contexto Captura Instantáneas

Antes de resolver el problema, entendámoslo en profundidad. Esto no es académico—saber por qué los valores de contexto no se actualizan te ayudará a depurar problemas, diseñar mejores APIs y evitar los frustrantes momentos de "¿por qué esto no funciona?" que afectan a los desarrolladores nuevos en el contexto de Svelte.

El Problema del Contador Congelado

Comencemos con código que parece perfectamente razonable pero no funciona:

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

	let { children } = $props()

	let count = 0

	setContext('count', count) // Captures 0

	function increment() {
		count++ // count becomes 1, 2, 3...
		// But context still holds 0!
	}
</script>

<button onclick={increment}>
	Provider sees: {count}
</button>

{@render children()}

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

	const count = getContext('count') // Gets 0, forever
</script>

<p>Consumer sees: {count}</p> <!-- Always 0, never updates! -->

El botón del proveedor muestra 1, 2, 3... pero el consumidor está atascado en 0 para siempre. Haz clic en el botón cien veces—nada cambia en el consumidor.

Lo Que Realmente Sucede Internamente

Cuando setContext('count', count) se ejecuta durante la inicialización del componente, JavaScript evalúa count en ese momento exacto y pasa el resultado a Svelte. Eso es todo. No se crea ningún vínculo mágico, no se establece ninguna suscripción, no se mantiene ninguna conexión continua.

Sigamos la ejecución paso a paso:

// Inside Provider.svelte's <script>

let count = 0

setContext('count', count)
// What happens internally:
// 1. JavaScript evaluates the expression 'count'
// 2. Since count is 0, the expression evaluates to the NUMBER 0
// 3. Svelte receives: setContext('count', 0)
// 4. Svelte stores in its context map: { 'count': 0 }
// 5. Done. The variable 'count' and the stored value are now independent.

function increment() {
	count++
	// The variable 'count' changes: 0 → 1 → 2 → 3...
	// But the context store still has: { 'count': 0 }
	// There's no link between them!
}

El Modelo Mental de la Fotografía

Piensa en setContext como tomar una fotografía. En el momento en que tomas la foto, capturas exactamente cómo se ve la escena. Si la escena cambia después—alguien se mueve, la iluminación cambia, pasan los años—tu fotografía no se actualiza. Está congelada en el tiempo.

Time 0 (component initialization):
┌─────────────────┐       snapshot    ┌─────────────────┐
│ Provider        │   ─────────────>  │ Context Store   │
│ count = 0       │                   │ 'count' → 0     │
└─────────────────┘                   └─────────────────┘

Time 1, 2, 3... (after increments):
┌─────────────────┐                   ┌─────────────────┐
│ Provider        │    (no link)      │ Context Store   │
│ count = 1, 2, 3 │                   │ 'count' → 0     │  ← Still 0!
└─────────────────┘                   └─────────────────┘

El almacén de contexto guarda una "fotografía" del valor en el tiempo 0. Cuando la variable original cambia, la fotografía permanece igual.

Por Qué JavaScript Funciona de Esta Manera

Este comportamiento no es una limitación de Svelte—es fundamental para cómo JavaScript maneja los valores primitivos. Cuando pasas un primitivo (número, cadena, booleano) a una función, JavaScript copia el valor:

let count = 0
const stored = count // stored gets the VALUE 0, not a reference to count

count = 100
console.log(count) // 100
console.log(stored) // Still 0!

Para los primitivos, JavaScript siempre copia el valor. No hay manera de crear una "referencia en vivo" a un primitivo—así simplemente no funciona el lenguaje.

Los Objetos Son Diferentes (Pero Siguen Siendo Complicados)

Los objetos se pasan por referencia, lo que significa que sucede algo diferente:

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

	let { children } = $props()

	const user = { name: 'Alice', score: 0 }

	setContext('user', user)
	// Context stores a REFERENCE to the same object in memory

	function addPoint() {
		user.score++ // Modifying the shared object
	}
</script>

<button onclick={addPoint}>Add Point</button>
{@render children()}

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

	const user = getContext('user')
	// Gets a reference to the SAME object as the provider
</script>

<p>Score: {user.score}</p>

Cuando el proveedor llama a addPoint(), el user.score del consumidor también cambia—ambos apuntan al mismo objeto en memoria. Pero todavía hay un problema: Svelte no sabe que ocurrió la mutación. El componente consumidor no se volverá a renderizar para mostrar el nuevo puntaje.

Aquí es donde entra $state.

El Modelo Mental de Svelte 5: Referencias Reactivas

La idea clave para el contexto reactivo es esta: necesitamos dos cosas funcionando juntas.

Una referencia compartida para que tanto el proveedor como el consumidor accedan a los mismos datos
El conocimiento de Svelte para que Svelte sepa cuándo cambian los datos y pueda actualizar la UI

Usar $state con un objeto nos da ambas.

El Patrón Fundamental

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

	let { children } = $props()

	// Step 1: Create reactive state as an OBJECT
	let counter = $state({ value: 0 })

	// Step 2: Share the reactive object via context
	setContext('counter', counter)

	function increment() {
		counter.value++ // Svelte tracks this mutation
	}
</script>

<button onclick={increment}>
	Provider: {counter.value}
</button>

{@render children()}

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

	// Step 3: Get the same reactive object
	const counter = getContext('counter')
</script>

<p>Consumer: {counter.value}</p>
<!-- Now this updates automatically! -->

Haz clic en el botón y observa cómo ambos números aumentan juntos. El consumidor ya no está congelado.

Por Qué Funciona: Trazando el Flujo de Datos

Sigamos lo que ocurre con este patrón:

Time 0 (initialization):
┌──────────────────┐              ┌─────────────────┐
│ Provider         │   reference  │ Context Store   │
│ counter          ┼─────────────>│ 'counter' ───┐  │
└──────────────────┘              └──────────────┼──┘
                                                 │
                    ┌────────────────────────────┘
                    │
                    ▼
            { value: 0 }  ← Reactive $state object in memory
                    ▲
                    │
┌──────────────────┐│
│ Consumer         ││
│ counter ─────────┘│
└───────────────────┘

Both Provider and Consumer point to the SAME object in memory.

Cuando el proveedor muta counter.value:

El sistema de reactividad de Svelte detecta el cambio (porque el objeto fue creado con $state)
Svelte marca cualquier componente que lea counter.value como que necesita re-renderizarse
El consumidor se vuelve a renderizar con el nuevo valor

El ingrediente mágico es $state. Sin él, tendrías un objeto compartido, pero Svelte no sabría cuándo cambió.

Los objetos se pasan por referencia en JavaScript. Cuando haces setContext('counter', counter), el contexto almacena una referencia al objeto—no una copia. El proveedor, el contexto y todos los consumidores apuntan al mismo objeto en memoria. Mutálo en cualquier lugar, y todos verán el cambio.

Por Qué los Primitivos No Funcionan Directamente

Un primitivo simple como let count = $state(0) no funcionará para el contexto porque no puedes compartir una referencia a él:

<!-- AVOID: This doesn't work as expected -->
<script>
	import { setContext } from 'svelte'

	let count = $state(0)

	setContext('count', count)
	// This stores the VALUE 0, not a reference to the $state
	// It's the same snapshot problem all over again!
</script>

Siempre envuelve en un objeto:

<!-- ✅ This works -->
<script>
	import { setContext } from 'svelte'

	let counter = $state({ value: 0 })

	setContext('counter', counter)
	// This stores a REFERENCE to the $state object
</script>

Esto puede parecer verboso al principio, pero es explícito y predecible. Siempre sabes que los valores de contexto son objetos que puedes mutar.

La Regla de Oro: Muta, No Reasignes

Ahora viene la regla más importante del contexto reactivo—la que hace tropezar a los desarrolladores más que cualquier otra. Entenderla en profundidad te ahorrará horas de depuración.

Cuando tienes un objeto de contexto reactivo, debes mutar sus propiedades. Nunca debes reasignar el objeto completo.

Esta regla no es negociable. Viólala, y tus consumidores dejarán de recibir actualizaciones silenciosamente.

Entendiendo la Mutación

La mutación significa cambiar una propiedad en un objeto existente—la identidad del objeto permanece igual, solo estás cambiando lo que contiene:

const user = $state({ name: 'Alice', score: 0 })

// ✅ Mutation: Changing existing properties
user.name = 'Bob'
user.score = 100

// ✅ Mutation: Adding new properties
user.email = 'bob@example.com'

// ✅ Mutation: Changing nested properties
user.settings = { theme: 'dark' }
user.settings.theme = 'light'

// ✅ Mutation: Array operations that modify in-place
user.friends = []
user.friends.push('Charlie')
user.friends.splice(0, 1)

Entendiendo la Reasignación

La reasignación significa apuntar la variable a un objeto completamente nuevo—esto es lo que rompe el contexto:

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

// ❌ Reassignment: Creating a new object
user = { name: 'Bob', score: 100 }

// ❌ Reassignment: Even with spread operator
user = { ...user, score: 100 }

// ❌ Reassignment: Creating fresh object from JSON
user = JSON.parse(JSON.stringify(user))

// ❌ Reassignment: Filter/map/etc return new arrays
user.friends = user.friends.filter((f) => f !== 'Dave')

Después de la reasignación, la variable apunta a un objeto completamente diferente.

Por Qué la Reasignación Rompe el Contexto

Recuerda: tanto el proveedor como el consumidor tienen referencias al mismo objeto. Cuando reasignas, rompes esa referencia compartida.

Con mutación (comportamiento correcto):

Before:
Provider.user ──────┐
                    ├──> { name: 'Alice', score: 0 }  (object at memory address 0x1234)
Consumer.user ──────┘

After user.score = 100:
Provider.user ──────┐
                    ├──> { name: 'Alice', score: 100 }  (same object at 0x1234, mutated)
Consumer.user ──────┘

Both still point to the same object. Consumer sees the change.

Con reasignación (comportamiento roto):

Before:
Provider.user ──────┐
                    ├──> { name: 'Alice', score: 0 }  (object at 0x1234)
Consumer.user ──────┘

After user = { name: 'Bob', score: 100 }:
Provider.user ──────────> { name: 'Bob', score: 100 }  (NEW object at 0x5678)

Consumer.user ──────────> { name: 'Alice', score: 0 }  (OLD object at 0x1234, orphaned!)

Consumer is now looking at an abandoned object. It will NEVER see updates again.

Un Escenario del Mundo Real: Proveedor de Configuraciones

Veamos cómo se desarrolla esto en un ejemplo realista que podrías llegar a construir:

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

	let { children } = $props()

	let settings = $state({
		theme: 'light',
		fontSize: 16,
		language: 'en',
		notifications: true
	})

	setContext('settings', settings)

	// ✅ CORRECT: Individual property changes
	function setDarkTheme() {
		settings.theme = 'dark'
	}

	function increaseFontSize() {
		settings.fontSize += 2
	}

	function toggleNotifications() {
		settings.notifications = !settings.notifications
	}

	// ❌ WRONG: Resetting by reassignment
	function resetSettingsBroken() {
		settings = { theme: 'light', fontSize: 16, language: 'en', notifications: true }
		// Provider now has a NEW object
		// All consumers still reference the OLD object
		// Future settings updates will NEVER reach consumers!
	}

	// ✅ CORRECT: Resetting by mutation
	function resetSettingsCorrect() {
		settings.theme = 'light'
		settings.fontSize = 16
		settings.language = 'en'
		settings.notifications = true
		// Same object, mutated properties
		// All consumers see the reset
	}

	// ✅ ALSO CORRECT: Using Object.assign
	function resetWithAssign() {
		Object.assign(settings, {
			theme: 'light',
			fontSize: 16,
			language: 'en',
			notifications: true
		})
		// Object.assign mutates the first argument
		// Same object, consumers see the change
	}
</script>

{@render children()}

Patrones Comunes que Reasignan Accidentalmente

Presta atención a estos patrones que parecen inocentes pero rompen el contexto:

let state = $state({ items: [] })

// ❌ Spread into new object
state = { ...state, items: [...state.items, newItem] }

// ✅ Push into existing array
state.items.push(newItem)

// ❌ Filter returns new array, then reassigns
state.items = state.items.filter((i) => i.id !== id)

// ✅ In-place array mutation with splice
const index = state.items.findIndex((i) => i.id === id)
if (index !== -1) state.items.splice(index, 1)

// ❌ Map returns new array
state.items = state.items.map((i) => (i.id === id ? { ...i, done: true } : i))

// ✅ Find and mutate directly
const item = state.items.find((i) => i.id === id)
if (item) item.done = true

// ❌ Creating fresh object from fetch response
const data = await response.json()
state = data // Reassignment!

// ✅ Merging fetch data into existing object
const data = await response.json()
Object.assign(state, data)

Cuando Necesitas Reemplazar un Objeto Completo

A veces necesitas reemplazar legítimamente un objeto completo—por ejemplo, reemplazar los datos de usuario después del login. En este caso, envuelve tus datos un nivel más profundo:

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

	let { children } = $props()

	// Outer container NEVER gets reassigned
	let container = $state({
		user: null
	})

	setContext('user', container)

	async function login(credentials) {
		const response = await fetch('/api/login', {
			method: 'POST',
			body: JSON.stringify(credentials)
		})
		const userData = await response.json()

		// ✅ Mutating container.user property
		// Even though we're replacing the whole user object,
		// we're doing it by mutating the container
		container.user = userData
	}

	function logout() {
		// ✅ Mutating container.user property
		container.user = null
	}
</script>

{@render children()}

Los consumidores acceden mediante container.user:

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

	const userContext = getContext('user')
</script>

{#if userContext.user}
	<p>Welcome, {userContext.user.name}!</p>
	<p>Email: {userContext.user.email}</p>
{:else}
	<p>Please log in</p>
{/if}

El contenedor exterior permanece igual; reemplazas lo que hay dentro. La cadena de referencias se mantiene intacta.

Avanzando hacia los Getters: La Conexión con la Reactividad

Ya dominas el patrón básico de los objetos $state. Ahora exploremos un enfoque más elegante que verás en código de producción: las funciones getter. Entender por qué funcionan los getters te permite crear APIs de contexto más limpias y flexibles.

El Problema con la Asignación Directa de Propiedades

Considera esta configuración de contexto aparentemente razonable:

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

	let { children } = $props()

	let theme = $state('light')

	// ❌ This looks right but captures the VALUE at this moment
	setContext('theme', {
		current: theme, // Captures 'light' forever!
		toggle() {
			theme = theme === 'light' ? 'dark' : 'light'
		}
	})
</script>

{@render children()}

Cuando este código se ejecuta, a current se le asigna el valor 'light'—un primitivo de tipo string. Incluso cuando theme cambia a 'dark', current sigue manteniendo 'light':

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

	const theme = getContext('theme')
</script>

<button onclick={theme.toggle}> Toggle Theme </button>

<p>Current: {theme.current}</p>
<!-- Always 'light', even after toggling! -->

La función toggle funciona—cambia la variable theme en el proveedor. Pero theme.current está congelada porque capturó un valor primitivo en el momento de la creación del objeto, no una referencia en vivo.

La Solución con Getters

Un getter es una función que se ejecuta cada vez que accedes a la propiedad. Lee el estado reactivo de forma actualizada, devolviendo cualquier valor que sea el actual:

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

	let { children } = $props()

	let theme = $state('light')

	// ✅ Getter reads the CURRENT value each time it's accessed
	setContext('theme', {
		get current() {
			return theme // Evaluates `theme` each time you read `current`
		},
		toggle() {
			theme = theme === 'light' ? 'dark' : 'light'
		}
	})
</script>

{@render children()}

Ahora cuando los consumidores acceden a theme.current, JavaScript llama a la función getter, que lee el valor actual de la variable $state. Si el estado cambió, obtienes el nuevo valor.

Comparación Visual

WITHOUT GETTER (property assignment):
┌──────────────────────┐     setContext     ┌──────────────────────────────┐
│ let theme = 'light'  │ ────────────────>  │ { current: 'light' }         │
│                      │                    │                              │
│ theme = 'dark'       │    (later)         │ { current: 'light' }  ← STALE!
└──────────────────────┘                    └──────────────────────────────┘

WITH GETTER:
┌──────────────────────┐     setContext     ┌──────────────────────────────┐
│ let theme = $state() │ ────────────────>  │ { get current() {            │
│                      │                    │     return theme;            │
│ (every read of       │                    │   }                          │
│  theme.current)──────│────────────────────│───> runs getter, returns     │
│                      │                    │       current theme value    │
└──────────────────────┘                    └──────────────────────────────┘

Sistema de Temas Completo con Getters

Aquí hay un ejemplo completo que muestra el patrón de getters en acción:

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

	let { initialTheme = 'light', children } = $props()

	let theme = $state(initialTheme)

	// Context object with getters for reactive access
	const themeContext = {
		// Getter: reads fresh value each time
		get current() {
			return theme
		},

		// Getter: computed property
		get isDark() {
			return theme === 'dark'
		},

		// Getter: another computed property
		get cssClass() {
			return `theme-${theme}`
		},

		// Actions: methods that mutate state
		set(newTheme) {
			theme = newTheme
		},

		toggle() {
			theme = theme === 'light' ? 'dark' : 'light'
		}
	}

	setContext('theme', themeContext)

	// Side effect: apply theme to document
	$effect(() => {
		document.documentElement.setAttribute('data-theme', theme)
	})
</script>

{@render children()}

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

	const theme = getContext('theme')
</script>

<button onclick={theme.toggle}>
	{theme.isDark ? '☀️ Switch to Light' : '🌙 Switch to Dark'}
</button>

<p>Current theme: {theme.current}</p>

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

	let { children } = $props()

	const theme = getContext('theme')
</script>

<div class="card" class:dark={theme.isDark}>
	{@render children()}
</div>

<style>
	.card {
		background: white;
		color: black;
		padding: 1rem;
		border-radius: 8px;
		transition:
			background 0.2s,
			color 0.2s;
	}

	.card.dark {
		background: #1a1a1a;
		color: white;
	}
</style>

Todos los consumidores reaccionan a los cambios de tema automáticamente porque acceden a theme.current, theme.isDark y theme.cssClass a través de getters que leen el $state reactivo.

Getters vs Mutación de Objetos: Cuándo Usar Cada Uno

Ambos patrones funcionan para el contexto reactivo, pero tienen diferentes fortalezas:

Patrón de mutación de objetos (más simple, acceso directo al estado):

<script>
	let state = $state({ theme: 'light', fontSize: 16 })
	setContext('settings', state)

	// Consumers read: settings.theme, settings.fontSize
	// Provider updates: state.theme = 'dark'
</script>

Es la mejor opción cuando:

Tu contexto es un contenedor de datos simple y directo
Los consumidores necesitan acceso directo a todas las propiedades
No necesitas valores calculados/derivados

Patrón de getters (más control, encapsulación):

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

	setContext('settings', {
		get theme() {
			return theme
		},
		get fontSize() {
			return fontSize
		},
		get isDark() {
			return theme === 'dark'
		}, // Computed!
		setTheme(t) {
			theme = t
		},
		increaseFontSize() {
			fontSize += 2
		}
	})
</script>

Es la mejor opción cuando:

Necesitas propiedades calculadas/derivadas (como isDark)
Quieres ocultar la estructura interna del estado
Quieres controlar cómo se modifica el estado (solo mediante métodos)
Tienes múltiples variables de estado relacionadas que no deberían estar todas expuestas directamente

Evitando el Uso Excesivo de $effect

Un error común es usar $effect para "sincronizar" valores de contexto. Esto casi siempre es incorrecto. Entender cuándo $effect es apropiado—y cuándo no lo es—te ayudará a escribir código más limpio y predecible.

La Forma Incorrecta: Sincronizar con $effect

<script>
	import { setContext } from 'svelte'

	let { user } = $props()

	let contextUser = $state(user)

	// ❌ Don't do this!
	$effect(() => {
		contextUser = user // Trying to "sync" props to context
	})

	setContext('user', {
		get current() {
			return contextUser
		}
	})
</script>

Por Qué Esto Es Incorrecto

Este patrón tiene múltiples problemas:

Indirección extra — Estás creando una copia del estado que refleja a otro
Problemas de temporización — Los effects se ejecutan después del render, causando posibles parpadeos
Complejidad innecesaria — Existe una solución mucho más simple
Posibles bucles infinitos — En casos complejos, puedes crear actualizaciones circulares

La Forma Correcta: Getter Directo

Si los datos provienen de props, simplemente usa el prop directamente en un getter:

<script>
	import { setContext } from 'svelte'

	let { user, children } = $props()

	// ✅ Getter reads prop directly
	setContext('user', {
		get current() {
			return user
		}
	})
</script>

{@render children()}

Sin $state, sin $effect, solo un getter que lee el prop. Cuando user cambia (porque el padre se vuelve a renderizar con nuevos datos), el getter devuelve el nuevo valor automáticamente.

Cuándo SÍ Es Apropiado $effect

Los effects son para efectos secundarios—cosas que ocurren fuera del modelo de componentes de Svelte:

<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let theme = $state('light')

	setContext('theme', {
		get current() {
			return theme
		},
		set(value) {
			theme = value
		}
	})

	// ✅ Side effect: Update the DOM outside Svelte's control
	$effect(() => {
		document.documentElement.setAttribute('data-theme', theme)
	})

	// ✅ Side effect: Persist to localStorage
	$effect(() => {
		localStorage.setItem('theme', theme)
	})

	// ✅ Side effect: Log analytics
	$effect(() => {
		console.log('Theme changed to:', theme)
		// Or: analytics.track('theme_changed', { theme });
	})
</script>

{@render children()}

Usa $effect cuando necesites:

Manipular el DOM directamente
Interactuar con APIs del navegador (localStorage, sessionStorage, etc.)
Llamar a servicios o APIs externos
Configurar suscripciones o listeners de eventos
Realizar logging o analíticas

El Modelo Mental de Tres Capas

Para consolidar tu comprensión, piensa en el contexto reactivo en tres capas distintas:

┌─────────────────────────────────────────────────────────────┐
│  LAYER 1: STATE (The Source of Truth)                       │
│  ────────────────────────────────────                       │
│  $state variables hold the actual data                      │
│                                                             │
│  let theme = $state('light');                               │
│  let items = $state([]);                                    │
│  let settings = $state({ fontSize: 16, lang: 'en' });       │
│                                                             │
│  This is where data lives. Only one copy exists.            │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  LAYER 2: CONTEXT OBJECT (The API)                          │
│  ─────────────────────────────────                          │
│  Getters expose state, methods mutate it                    │
│                                                             │
│  setContext('app', {                                        │
│    get theme() { return theme; },                           │
│    get isDark() { return theme === 'dark'; },               │
│    setTheme(t) { theme = t; }                               │
│  });                                                        │
│                                                             │
│  This shapes what consumers see and how they interact.      │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  LAYER 3: CONSUMERS (The Users)                             │
│  ──────────────────────────────                             │
│  Read through getters, call methods, trigger UI updates     │
│                                                             │
│  const app = getContext('app');                             │
│  <p>{app.theme}</p>  <!-- Re-renders when theme changes --> │
│  <button onclick={() => app.setTheme('dark')}>Dark</button> │
│                                                             │
│  Components read and respond. They don't manage state.      │
└─────────────────────────────────────────────────────────────┘

Cada capa tiene una responsabilidad específica:

Capa 1 contiene la verdad — $state es la fuente única
Capa 2 da forma a la API — los getters exponen lo que los consumidores necesitan, los métodos controlan cómo cambia el estado
Capa 3 consume reactivamente — los componentes leen y responden a los cambios

Errores Comunes y Anti-Patrones

<script>
	let count = $state(0)
	setContext('count', count) // AVOID: Captures 0, not the reactive state
</script>

Por qué falla: Los primitivos se copian por valor. El contexto almacena el número 0, no una referencia a tu $state.

Solución: Envuelve en un objeto con un getter:

<script>
	let count = $state(0)
	setContext('count', {
		get value() {
			return count
		},
		set(v) {
			count = v
		}
	})
</script>

<script>
	let state = $state({ count: 0 })
	setContext('counter', state)

	function reset() {
		// ❌ This breaks the reference!
		state = { count: 0 }
	}
</script>

Por qué falla: El contexto mantiene una referencia al objeto original. Cuando reasignas state, creas un nuevo objeto. El contexto sigue apuntando al anterior.

Solución: Muta el objeto existente:

<script>
	function reset() {
		state.count = 0 // ✅ Mutate the property
	}
</script>

<script>
	let state = $state({ items: [1, 2, 3] })
	setContext('list', state)

	function removeFirst() {
		// ❌ filter() returns a NEW array
		state.items = state.items.filter((_, i) => i !== 0)
	}
</script>

Por qué falla: Aunque estás mutando state.items (lo cual está bien), estás reemplazando la referencia al array. Esto funciona para los consumidores directos de state.items, pero si algún consumidor almacenó en caché una referencia al array anterior, tendrá datos desactualizados.

Solución: Usa mutación en el lugar:

<script>
	function removeFirst() {
		state.items.splice(0, 1) // ✅ Mutates array in place
	}
</script>

<script>
	let { user } = $props()
	let contextUser = $state(user)

	// ❌ Don't do this!
	$effect(() => {
		contextUser = user // Trying to "sync" props to context
	})

	setContext('user', {
		get current() {
			return contextUser
		}
	})
</script>

Por qué está mal: Indirección adicional, problemas de temporización (los efectos se ejecutan después del renderizado) y complejidad innecesaria.

Solución: Usa un getter que lea el prop directamente:

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

	// ✅ Getter reads prop directly
	setContext('user', {
		get current() {
			return user
		}
	})
</script>

Verificando Tu Comprensión

Pongamos a prueba tu dominio de estos conceptos. Para cada escenario, predice si el consumidor verá las actualizaciones.

Escenario 1

<!-- Provider -->
<script>
  let data = $state({ count: 0 });
  setContext('data', data);

  function increment() {
    data.count++;
  }
</script>

<!-- Consumer -->
<script>
  const data = getContext('data');
</script>
<p>{data.count}</p>

Respuesta: ✅ Sí, se actualiza. data.count++ muta el objeto existente. Tanto el proveedor como el consumidor hacen referencia al mismo objeto $state.

Escenario 2

<!-- Provider -->
<script>
  let count = $state(0);
  setContext('count', count);

  function increment() {
    count++;
  }
</script>

<!-- Consumer -->
<script>
  const count = getContext('count');
</script>
<p>{count}</p>

Respuesta: ❌ No, no se actualiza. Los primitivos se copian por valor. El consumidor obtuvo 0 al inicializarse y nunca ve los cambios.

Escenario 3

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

  function changeName() {
    user = { name: 'Bob' };  // Reassignment
  }
</script>

<!-- Consumer -->
<script>
  const user = getContext('user');
</script>
<p>{user.name}</p>

Respuesta: ❌ No, no se actualiza. La reasignación crea un nuevo objeto. El consumidor sigue haciendo referencia al objeto anterior que muestra 'Alice'.

Escenario 4

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

  function changeName() {
    user.name = 'Bob';  // Mutation
  }
</script>

<!-- Consumer -->
<script>
  const user = getContext('user');
</script>
<p>{user.name}</p>

Respuesta: ✅ Sí, se actualiza. user.name = 'Bob' muta el objeto existente. Ambos siguen haciendo referencia al mismo objeto.

Escenario 5

<!-- Provider -->
<script>
  let theme = $state('light');
  setContext('theme', {
    get current() { return theme; },
    toggle() { theme = theme === 'light' ? 'dark' : 'light'; }
  });
</script>

<!-- Consumer -->
<script>
  const theme = getContext('theme');
</script>
<p>{theme.current}</p>

Respuesta: ✅ Sí, se actualiza. El getter lee theme de forma fresca cada vez. Cuando toggle() cambia theme, la siguiente lectura de theme.current devuelve el nuevo valor.

Ejemplo Completo para Producción

Pongamos todo junto en un ejemplo integral — un rastreador de puntuación que demuestra todos los patrones que hemos cubierto usando el patrón de getter.

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

	let { children } = $props()

	// Layer 1: State (source of truth)
	let points = $state(0)
	let multiplier = $state(1)
	let history = $state([])

	// Layer 2: Context object (the API)
	const scoreContext = {
		// Getters for reactive access
		get points() {
			return points
		},

		get multiplier() {
			return multiplier
		},

		get history() {
			return history
		},

		// Computed properties via getters
		get totalWithMultiplier() {
			return points * multiplier
		},

		get hasHistory() {
			return history.length > 0
		},

		// Methods for controlled mutations
		addPoints(amount) {
			const earned = amount * multiplier
			points += earned
			history.push({
				timestamp: Date.now(),
				amount: earned,
				total: points
			})
		},

		doubleMultiplier() {
			multiplier *= 2
		},

		reset() {
			points = 0
			multiplier = 1
			history.length = 0 // Clear array in place
		}
	}

	setContext('score', scoreContext)
</script>

{@render children()}

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

	const score = getContext('score')
</script>

<div class="score-display">
	<h2>Score: {score.points}</h2>
	<p>Multiplier: {score.multiplier}×</p>
	<p>Effective total: {score.totalWithMultiplier}</p>
</div>

<style>
	.score-display {
		padding: 1rem;
		background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
		color: white;
		border-radius: 8px;
		text-align: center;
	}

	h2 {
		margin: 0 0 0.5rem;
		font-size: 2rem;
	}

	p {
		margin: 0.25rem 0;
		opacity: 0.9;
	}
</style>

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

	const score = getContext('score')
</script>

<div class="controls">
	<button onclick={() => score.addPoints(10)}>+10 points</button>
	<button onclick={() => score.addPoints(50)}>+50 points</button>
	<button onclick={() => score.doubleMultiplier()}>Double Multiplier</button>
	<button onclick={() => score.reset()} class="reset">Reset</button>
</div>

<style>
	.controls {
		display: flex;
		gap: 0.5rem;
		flex-wrap: wrap;
	}

	button {
		padding: 0.5rem 1rem;
		border: none;
		border-radius: 4px;
		background: #3b82f6;
		color: white;
		cursor: pointer;
		font-weight: 500;
	}

	button:hover {
		background: #2563eb;
	}

	button.reset {
		background: #ef4444;
	}

	button.reset:hover {
		background: #dc2626;
	}
</style>

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

	const score = getContext('score')

	function formatTime(timestamp) {
		return new Date(timestamp).toLocaleTimeString()
	}
</script>

<div class="history">
	<h3>History ({score.history.length} entries)</h3>

	{#if score.hasHistory}
		<ul>
			{#each score.history as entry, i (entry.timestamp)}
				<li>
					<span class="index">#{i + 1}</span>
					<span class="amount">+{entry.amount}</span>
					<span class="total">→ {entry.total} total</span>
					<span class="time">{formatTime(entry.timestamp)}</span>
				</li>
			{/each}
		</ul>
	{:else}
		<p class="empty">No points scored yet</p>
	{/if}
</div>

<style>
	.history {
		padding: 1rem;
		background: #f3f4f6;
		border-radius: 8px;
	}

	h3 {
		margin: 0 0 0.75rem;
		color: #374151;
	}

	ul {
		list-style: none;
		padding: 0;
		margin: 0;
	}

	li {
		display: flex;
		gap: 0.75rem;
		padding: 0.5rem 0;
		border-bottom: 1px solid #e5e7eb;
		font-size: 0.875rem;
	}

	li:last-child {
		border-bottom: none;
	}

	.index {
		color: #9ca3af;
		font-weight: 500;
	}

	.amount {
		color: #059669;
		font-weight: 600;
	}

	.total {
		color: #374151;
	}

	.time {
		margin-left: auto;
		color: #9ca3af;
		font-size: 0.75rem;
	}

	.empty {
		color: #9ca3af;
		font-style: italic;
		margin: 0;
	}
</style>

<!-- +page.svelte -->
<script>
	import ScoreProvider from './ScoreProvider.svelte'
	import ScoreDisplay from './ScoreDisplay.svelte'
	import ScoreControls from './ScoreControls.svelte'
	import ScoreHistory from './ScoreHistory.svelte'
</script>

<ScoreProvider>
	<main>
		<h1>Score Tracker</h1>
		<ScoreDisplay />
		<ScoreControls />
		<ScoreHistory />
	</main>
</ScoreProvider>

<style>
	main {
		max-width: 600px;
		margin: 2rem auto;
		padding: 1rem;
		display: flex;
		flex-direction: column;
		gap: 1rem;
	}

	h1 {
		text-align: center;
		color: #1f2937;
	}
</style>

Los tres componentes consumidores comparten el mismo contexto. Cuando ScoreControls llama a score.addPoints(), tanto ScoreDisplay como ScoreHistory se vuelven a renderizar automáticamente para mostrar los valores actualizados.

Tabla de Referencia Rápida

Patrón	¿Funciona?	Por qué
`$state({ value: 0 })` + `value++`	✅	Mutación de objeto, Svelte lo rastrea
`$state(0)` directamente en contexto	❌	Primitivo copiado por valor
`object.property = newValue`	✅	La mutación preserva la referencia
`object = { ...object }`	❌	La reasignación rompe la referencia
`array.push(item)`	✅	Mutación en el lugar
`array = array.filter(...)`	❌	Crea un nuevo array
`array.splice(index, 1)`	✅	Mutación en el lugar
`Object.assign(obj, newData)`	✅	Muta el primer argumento
`get prop() { return $state }`	✅	El getter lee el valor actualizado
`prop: $state` en objeto literal	❌	Captura el valor al momento de creación

Consideraciones de Rendimiento y Escalabilidad

El contexto reactivo es eficiente, pero entender sus características de rendimiento te ayuda a escalar con confianza.

Actualizaciones Granulares

La reactividad de Svelte es granular. Cuando mutas una propiedad específica, solo los componentes que leen ese valor específico se vuelven a renderizar—no todos los componentes que leen cualquier parte del objeto de contexto. Esto significa que puedes tener objetos de estado complejos sin preocuparte por actualizaciones en cascada.

Arrays y Objetos Grandes

Para arrays grandes (cientos o miles de elementos), considera usar un Map para búsqueda O(1) en lugar de iterar:

<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let items = $state([])
	let itemsById = new Map()

	const listContext = {
		get items() {
			return items
		},

		add(item) {
			items.push(item)
			itemsById.set(item.id, item)
		},

		getById(id) {
			return itemsById.get(id)
		},

		updateById(id, updates) {
			const item = itemsById.get(id)
			if (item) {
				Object.assign(item, updates) // Mutate in place
			}
		}
	}

	setContext('list', listContext)
</script>

{@render children()}

Consideraciones de Memoria

Los objetos de contexto persisten durante toda la vida útil del componente proveedor. Si estás almacenando grandes cantidades de datos, considera estrategias de limpieza:

<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let cache = $state(new Map())
	const maxSize = 100

	const cacheContext = {
		set(key, value) {
			// Evict oldest if at capacity
			if (cache.size >= maxSize) {
				const firstKey = cache.keys().next().value
				cache.delete(firstKey)
			}
			cache.set(key, value)
		},

		get(key) {
			return cache.get(key)
		}
	}

	setContext('cache', cacheContext)
</script>

{@render children()}

Conclusión

El contexto reactivo no es magia—es la consecuencia natural de entender cómo JavaScript maneja los valores y cómo Svelte rastrea los cambios. Cuando ves que el contexto "no funciona", casi siempre estás viendo una de dos cosas: primitivos que se copian por valor en lugar de referenciarse, o reasignaciones que rompen las referencias compartidas.

El patrón de objeto $state resuelve ambos problemas de forma elegante. Al envolver tus datos en un objeto y compartir ese objeto a través del contexto, estableces una única fuente de verdad que múltiples componentes pueden tanto leer como modificar. El sistema de reactividad de Svelte se encarga del resto—rastreando qué componentes dependen de qué propiedades y volviéndolos a renderizar cuando esas propiedades cambian.

El patrón getter lleva esto más lejos, permitiéndote exponer propiedades computadas y ocultar detalles de implementación internos mientras mantienes APIs limpias y predecibles.

La regla de oro de "mutar, no reasignar" puede sentirse restrictiva al principio, pero en realidad es liberadora una vez que la internalizas. Nunca tendrás que preguntarte si tu contexto está sincronizado entre componentes. Mientras estés mutando el mismo objeto, todos ven los mismos datos. Es un modelo mental simple que escala desde contadores triviales hasta estados de aplicación complejos.

Con estos fundamentos en su lugar, estás equipado para construir contexto que permanezca sincronizado en todo tu árbol de componentes—la base para todo, desde sistemas de temas hasta carritos de compras y funcionalidades de colaboración en tiempo real.

Puntos Clave

El contexto simple captura una instantánea. Cuando llamas a setContext(key, value), Svelte almacena ese valor tal como está. Para primitivos, eso es una copia. Para objetos, es una referencia. De cualquier manera, no hay una conexión continua—los cambios en la variable original no actualizan automáticamente el valor almacenado.

$state con objetos crea reactividad. Al envolver tus datos en un objeto $state y compartir ese objeto a través del contexto, tanto el proveedor como el consumidor mantienen referencias al mismo objeto reactivo. Cuando mutas las propiedades del objeto, Svelte rastrea el cambio y actualiza todos los componentes que leen esas propiedades.

Muta propiedades, nunca reasignes el objeto. Esta es la regla de oro. La mutación preserva la referencia compartida. La reasignación crea un nuevo objeto, dejando a los consumidores con una referencia huérfana a los datos anteriores. Siempre cambia propiedades (obj.prop = newValue), nunca reemplaces el objeto completo (obj = newObject).

Los getters garantizan frescura. Usa funciones getter (get prop()) cuando necesites valores computados o cuando quieras encapsular estado interno. Los getters se ejecutan en cada acceso, devolviendo siempre el valor actual.

Evita $effect para sincronizar. Si los datos provienen de props, usa un getter. Reserva $effect para efectos secundarios reales como manipulación del DOM, persistencia en localStorage o llamadas a APIs externas.

Piensa en tres capas. Estado (fuente de verdad) → Objeto de Contexto (la API) → Consumidores (los usuarios). Cada capa tiene un trabajo específico, y mantenerlas separadas hace que tu código sea mantenible.

¿Qué Sigue?

Construye sobre estos fundamentos con patrones avanzados en Contexto Basado en Clases, donde aprenderás a usar clases de TypeScript con $state para un contexto encapsulado y con tipos seguros que escala a aplicaciones complejas.

Ver También

Documentación Oficial

$state — Runa de estado reactivo
Svelte Context — Guía oficial de contexto