Estado Reactivo que Simplemente Funciona

El rune $state es la base del sistema de reactividad de Svelte 5. Transforma variables JavaScript ordinarias en estado reactivo que automáticamente activa actualizaciones en la UI cuando cambia. A diferencia de otros frameworks que requieren objetos envolventes o funciones setter, Svelte te permite trabajar con valores reactivos igual que con variables normales—el compilador se encarga de la magia detrás de escena.

Este tutorial te lleva desde el uso básico hasta patrones avanzados, cubriendo reactividad profunda, mecánicas de proxy, optimización de rendimiento con $state.raw, y los errores comunes que hacen tropezar incluso a desarrolladores experimentados.

¿Qué Es `$state`?

$state es un rune que hace que una variable sea reactiva. Cuando una variable reactiva cambia, Svelte actualiza automáticamente cualquier parte de tu UI que la use.

Uso Básico

Este es el ejemplo más simple posible:

<script>
	let count = $state(0)
</script>

<button onclick={() => count++}>
	Clicks: {count}
</button>

Analicemos esto paso a paso:

let count = $state(0) - Crea una variable reactiva llamada count con un valor inicial de 0
onclick={() => count++} - Cuando se hace clic, incrementa count en 1
{count} - Muestra el valor actual de count en el texto del botón

¿Qué sucede cuando haces clic?

El manejador de clic ejecuta count++
Svelte detecta que count cambió
Svelte actualiza automáticamente el texto del botón para mostrar el nuevo valor

Nunca tienes que actualizar el DOM manualmente. ¡Ese es el poder de la reactividad!

Por Qué `$state` Es Diferente de Otros Frameworks

Si has usado React, Vue u otros frameworks, es probable que estés acostumbrado/a a una sintaxis como esta:

// React
const [count, setCount] = useState(0)
setCount(count + 1) // Must use setter function

// Vue
const count = ref(0)
count.value++ // Must use .value

Svelte es diferente. Con $state, interactúas con la variable directamente:

// Svelte 5
let count = $state(0)
count++ // Just use it like a normal variable!

Sin objetos envolventes, sin funciones setter, sin .value. Es simplemente un número, y lo usas como un número. Esta es la filosofía de Svelte: mantener las cosas simples y cercanas al JavaScript nativo.

Cómo Funciona Internamente (Simplificado)

Cuando escribes let count = $state(0), el compilador de Svelte transforma tu código. Esta es una versión simplificada de lo que sucede:

// What you write:
let count = $state(0)
console.log(count)
count++

// What Svelte compiles it to (conceptually):
let count_signal = createSignal(0)

console.log(getSignalValue(count_signal)) // Reading
setSignalValue(count_signal, getSignalValue(count_signal) + 1) // Writing

El compilador envuelve cada lectura y escritura de la variable con funciones especiales que:

Rastrean qué partes de la UI dependen de esta variable
Notifican a esas partes cuando la variable cambia

¿Por qué importa esto? Explica por qué los runes solo funcionan en archivos .svelte y .svelte.js/.svelte.ts—estos son los únicos archivos que el compilador de Svelte procesa.

¿Dónde Puedes Usar `$state`?

Puedes usar $state en:

Ubicación	Ejemplo
Bloques `<script>` de componentes	`let name = $state('Alice')`
Archivos `.svelte.js` / `.svelte.ts`	Para estado reactivo compartido
Campos de clase	`class Counter { count = $state(0) }`

No puedes usar $state en:

Archivos .js o .ts regulares (el compilador no los procesa)
Fuera del bloque <script> en un archivo .svelte

Preguntas Frecuentes de Principiantes

P: ¿Qué pasa si no uso $state?

Sin $state, los cambios no actualizarán la UI:

<script>
	let count = 0 // NOT reactive!
</script>

<button onclick={() => count++}>
	Clicks: {count}
	<!-- Will always show 0! -->
</button>

La variable cambia internamente, pero Svelte no lo sabe, por lo que la UI nunca se actualiza.

P: ¿Puedo usar $state con cualquier tipo de valor?

¡Sí! $state funciona con cualquier valor JavaScript:

<script>
	let count = $state(0) // Number
	let name = $state('Alice') // String
	let isActive = $state(true) // Boolean
	let user = $state({ name: 'Bob' }) // Object
	let items = $state([1, 2, 3]) // Array
	let nothing = $state(null) // null
</script>

Reactividad Profunda: La Magia del Proxy

¿Qué Es la Reactividad Profunda?

Cuando pasas un objeto o arreglo a $state, algo especial ocurre: Svelte lo hace profundamente reactivo. Esto significa que los cambios en propiedades anidadas (sin importar qué tan profundas estén) automáticamente activan actualizaciones en la UI.

Entendiendo el Concepto: Una Analogía Simple

Piensa en la reactividad profunda como un sistema de seguridad en un edificio.

Con monitoreo superficial (variables regulares), solo vigilas la puerta principal. Si alguien entra por una ventana o la puerta trasera, no te das cuenta.

Con monitoreo profundo (objetos/arreglos con $state), tienes cámaras en cada habitación, cada pasillo, cada clóset. Cualquier cambio en cualquier parte del edificio activa una alerta.

Cómo Funciona la Reactividad Profunda

Cuando creas un objeto reactivo:

<script>
	let user = $state({
		name: 'Alice',
		address: {
			city: 'New York',
			zip: '10001'
		}
	})
</script>

Svelte envuelve el objeto en un Proxy. Un Proxy es una característica de JavaScript que intercepta operaciones sobre un objeto—como leer o escribir propiedades.

Esto es lo que sucede cuando cambias una propiedad anidada:

<script>
	// Changing a deeply nested property
	user.address.city = 'Los Angeles'
</script>

<!-- This automatically updates! --><p>City: {user.address.city}</p>

Paso a paso:

Escribes en user.address.city
El Proxy intercepta esta operación de escritura
Svelte registra que user.address.city cambió
Svelte encuentra todos los elementos de UI que usan user.address.city
Svelte actualiza solo esos elementos (¡no la página completa!)

Reactividad Profunda con Arreglos

Los arreglos reciben el mismo tratamiento de reactividad profunda, incluyendo sus métodos:

<script>
	let todos = $state([
		{ id: 1, text: 'Learn Svelte 5', done: false },
		{ id: 2, text: 'Build an app', done: false }
	])
</script>

<ul>
	{#each todos as todo}
		<li>
			<input type="checkbox" checked={todo.done} onchange={() => (todo.done = !todo.done)} />
			{todo.text}
		</li>
	{/each}
</ul>

<button onclick={() => todos.push({ id: 3, text: 'New task', done: false })}> Add Todo </button>

Lo que es increíble aquí:

Los métodos de arreglo funcionan: todos.push() activa una actualización. Lo mismo ocurre con pop(), splice(), shift(), etc.
Los objetos anidados son reactivos: Cambiar todo.done actualiza solo esa casilla de verificación
Los nuevos elementos se vuelven reactivos: Cuando agregas un nuevo objeto con push, automáticamente se vuelve reactivo también
Actualizaciones granulares: Marcar una casilla no vuelve a renderizar toda la lista—solo ese elemento específico

Representación Visual de la Reactividad Profunda

$state({                          ← Proxy wrapper
  name: 'Alice',                  ← Reactive property
  preferences: {                  ← Nested Proxy wrapper
    theme: 'dark',                ← Reactive property
    notifications: {              ← Another nested Proxy wrapper
      email: true,                ← Reactive property
      push: false                 ← Reactive property
    }
  }
})

Cada nivel de anidamiento obtiene su propio envoltorio Proxy, haciendo que todas las propiedades sean reactivas.

La reactividad profunda permite actualizaciones granulares. Cuando cambias user.address.city, solo los elementos de UI que dependen de esa propiedad específica se vuelven a renderizar—no el componente completo.

Qué se convierte en Proxy (y qué no)

Svelte envuelve las cosas en Proxies recursivamente hasta que encuentra algo que no es un objeto plano o un array.

Estas SÍ se vuelven profundamente reactivas:

<script>
	// Plain objects - YES
	let config = $state({ theme: 'dark' })

	// Arrays - YES
	let items = $state([1, 2, 3])

	// Nested combinations - YES
	let data = $state({
		users: [{ name: 'Alice', scores: [95, 87, 92] }]
	})
</script>

Estas NO se vuelven profundamente reactivas:

<script>
	// Class instances - NO
	class Person {
		constructor(name) {
			this.name = name
		}
	}
	let person = $state(new Person('Alice'))
	// person.name is NOT reactive!

	// Built-in objects - NO
	let date = $state(new Date())
	let map = $state(new Map())
	let set = $state(new Set())
	// Changes to these won't trigger updates!

	// Objects created with Object.create() - NO
	let weird = $state(Object.create(null))
</script>

¿Por qué la distinción?

Los objetos planos y los arrays son las estructuras de datos más comunes, y Svelte puede envolverlos de forma segura. Pero las instancias de clases tienen comportamiento personalizado (métodos, getters, etc.) con los que los Proxies podrían interferir. Los objetos integrados como Map y Set tienen slots internos a los que los Proxies no pueden acceder.

Clases integradas reactivas de Svelte

Svelte incluye SvelteMap, SvelteSet, SvelteDate y SvelteURL en svelte/reactivity. Usa estos reemplazos directos siempre que necesites colecciones o fechas reactivas — funcionan exactamente igual que sus contrapartes nativas.

Para Map, Set, Date y URL, Svelte provee versiones reactivas que puedes importar:

<script>
	import { SvelteMap, SvelteSet, SvelteDate, SvelteURL } from 'svelte/reactivity'

	let myMap = new SvelteMap()
	let mySet = new SvelteSet()
	let myDate = new SvelteDate()
	let myUrl = new SvelteURL('https://example.com')
</script>

Estas funcionan como sus contrapartes nativas pero son completamente reactivas.

Cuándo se rompe la reactividad

Entender cuándo la reactividad no funciona es igual de importante que saber cuándo sí lo hace. Estos son los errores más comunes que cometen los desarrolladores.

1: La desestructuración rompe la reactividad

Desestructurar un objeto $state te da valores de JavaScript planos — no referencias reactivas. Los cambios en el objeto original no actualizarán las variables desestructuradas.

Qué sucede: Cuando desestructuras un objeto reactivo, extraes los valores actuales en ese momento — no referencias reactivas.

Analogía: Imagina tomar una foto de un reloj. La foto muestra la hora en que la tomaste, pero no se actualiza a medida que pasa el tiempo. La desestructuración es como tomar una foto de tus datos.

<script>
	let todo = $state({ done: false, text: 'Learn Svelte' })

	// AVOID: This takes a "photo" of the current values
	let { done, text } = todo

	function toggle() {
		// This changes the original todo...
		todo.done = !todo.done

		// ...but 'done' variable still has the old value!
		console.log(done) // Still false!
		console.log(todo.done) // true!
	}
</script>

<!-- AVOID: This won't update when todo.done changes -->
<p>Done (broken): {done}</p>

<!-- PREFERRED: This WILL update -->
<p>Done (works): {todo.done}</p>

Por qué sucede:

let { done, text } = todo

Esto es equivalente a:

let done = todo.done // Gets the value false
let text = todo.text // Gets the value 'Learn Svelte'

done ahora es simplemente una variable normal que contiene false. Ya no tiene ninguna conexión con todo.

La solución: Siempre accede a las propiedades a través del objeto reactivo.

<script>
	let todo = $state({ done: false, text: 'Learn Svelte' })

	// PREFERRED: Access through the object in your template
</script>

<p>Done: {todo.done}</p><p>Text: {todo.text}</p>

Cuándo la desestructuración SÍ es válida:

La desestructuración está bien cuando necesitas una instantánea en un momento dado:

<script>
	let form = $state({ name: 'Alice', email: 'alice@example.com' })

	function submitForm() {
		// Destructure to get current values for submission
		const { name, email } = form

		// Send to server (we want the values at this moment)
		fetch('/api/submit', {
			method: 'POST',
			body: JSON.stringify({ name, email })
		})
	}
</script>

2: Reasignar vs. Mutar

¿Cuál es la diferencia?

Mutar: Cambiar algo dentro de un objeto/array
Reasignar: Reemplazar el objeto/array completo por uno nuevo

<script>
	let items = $state(['a', 'b', 'c'])

	// PREFERRED: MUTATING - modifying the existing array
	function addWithMutation() {
		items.push('d') // Works!
		items[0] = 'A' // Works!
		items.splice(1, 1) // Works!
	}

	// PREFERRED: REASSIGNING - replacing with a new array
	function addWithReassign() {
		items = [...items, 'd'] // Works!
		items = items.map((i) => i.toUpperCase()) // Works!
		items = items.filter((i) => i !== 'b') // Works!
	}
</script>

Ambos enfoques funcionan con $state. La diferencia importa para:

Rendimiento (ver sección posterior)
$state.raw (solo funciona la reasignación)
Preferencias de estilo de código

Entendiendo el modelo mental:

MUTATION (modifying in place):
┌─────────────────┐
│ items = [a,b,c] │
└────────┬────────┘
         │ items.push('d')
         ▼
┌─────────────────┐
│ items = [a,b,c,d] │  ← Same array, modified
└─────────────────┘

REASSIGNMENT (replacing entirely):
┌─────────────────┐
│ items = [a,b,c] │  ← Old array (garbage collected)
└─────────────────┘
         │ items = [...items, 'd']
         ▼
┌─────────────────┐
│ items = [a,b,c,d] │  ← Brand new array
└─────────────────┘

3: Pasar estado a funciones (el problema del paso por valor)

Qué sucede: JavaScript pasa valores, no referencias. Cuando pasas un valor de $state a una función, estás pasando el valor actual en ese momento.

Analogía: Es como decirle a alguien un número de teléfono verbalmente. Si luego cambias tu número de teléfono, esa persona todavía tiene el viejo anotado.

<script>
	function addNumbers(a, b) {
		return a + b
	}

	let x = $state(1)
	let y = $state(2)

	// AVOID: total is calculated ONCE with values 1 and 2
	let total = addNumbers(x, y)

	function increment() {
		x++
		y++
		// x is now 2, y is now 3
		// But total is STILL 3!
	}
</script>

<p>x: {x}, y: {y}</p>
<p>Total: {total}</p>
<!-- Always shows 3, never updates! -->

Por qué sucede:

Cuando se llama a addNumbers(x, y):

x se evalúa como 1
y se evalúa como 2
La función recibe los valores 1 y 2
Retorna 3
total se establece en 3

Los cambios posteriores en x e y no vuelven a ejecutar addNumbers.

La solución: Usar $derived

<script>
	let x = $state(1)
	let y = $state(2)

	// PREFERRED: $derived recalculates whenever x or y changes
	let total = $derived(x + y)
</script>

<p>x: {x}, y: {y}</p>
<p>Total: {total}</p>
<!-- Updates correctly! -->

Solución alternativa: Pasar un objeto

Si necesitas pasar estado a una función, pasa un objeto en lugar de primitivos:

<script>
	function calculateTotal(data) {
		// Accesses current values each time it's called
		return data.x + data.y
	}

	let data = $state({ x: 1, y: 2 })

	// PREFERRED: This accesses the reactive object each time
	let total = $derived(calculateTotal(data))
</script>

4: Las instancias de clases no se convierten en Proxy

Qué sucede: Cuando envuelves una instancia de clase en $state, la instancia en sí no se vuelve reactiva. Solo los objetos planos y los arrays reciben el tratamiento de Proxy.

<script>
	class ShoppingCart {
		items = []

		addItem(item) {
			this.items.push(item)
		}

		get total() {
			return this.items.reduce((sum, item) => sum + item.price, 0)
		}
	}

	// AVOID:The class instance isn't reactive!
	let cart = $state(new ShoppingCart())

	function addProduct() {
		cart.addItem({ name: 'Widget', price: 9.99 })
		// UI won't update! cart.items.length still shows 0 in the UI
	}
</script>

<p>Items: {cart.items.length}</p>
<!-- Stuck at 0! -->

Por qué sucede: Las clases a menudo tienen métodos, getters, setters y lógica interna con los que los Proxies podrían interferir. Svelte actúa con cautela y no las convierte en Proxy.

La solución: Usar $state dentro de los campos de la clase

<script>
	class ShoppingCart {
		// PREFERRED: Make the items array reactive with $state
		items = $state([])

		addItem(item) {
			this.items.push(item) // Now triggers updates!
		}

		// Getters automatically work with reactive data
		get total() {
			return this.items.reduce((sum, item) => sum + item.price, 0)
		}

		get itemCount() {
			return this.items.length
		}
	}

	let cart = new ShoppingCart() // No $state wrapper needed!
</script>

<p>Items: {cart.itemCount}</p>
<p>Total: ${cart.total.toFixed(2)}</p>

<button onclick={() => cart.addItem({ name: 'Widget', price: 9.99 })}> Add Widget </button>

Punto clave: Pon $state en los campos reactivos, no en la instancia de la clase.

5: Exportar estado entre módulos

Exportar un primitivo $state y reasignarlo dentro de otro módulo no propagará la actualización. En su lugar, exporta un objeto y muta sus propiedades — o usa funciones getter.

Qué sucede: No puedes exportar directamente una variable $state que se reasigna.

// AVOID: state.svelte.js - This WON'T work!
export let count = $state(0)

export function increment() {
	count++ // Other files won't see this change!
}

Por qué sucede: El compilador de Svelte transforma cada archivo de forma independiente. Cuando otro archivo importa count, obtiene una referencia que el compilador en ese archivo no sabe cómo manejar.

La solución: Opción 1 - Exportar un objeto

// PREFERRED: state.svelte.js - Export an object instead
export const counter = $state({ count: 0 })

export function increment() {
	counter.count++ // Mutating a property works!
}

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

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

La solución: Opción 2 - Usar funciones getter

// PREFERRED: state.svelte.js - Don't export the variable directly
let count = $state(0)

export function getCount() {
	return count
}

export function increment() {
	count++
}

<!-- App.svelte -->
<script>
	import { getCount, increment } from './state.svelte.js'
</script>

<button onclick={increment}>
	Count: {getCount()}
</button>

6: El problema de la vinculación de `this` en clases

Qué sucede: Cuando pasas un método de clase como manejador de eventos, this puede no ser lo que esperas.

<script>
	class Counter {
		count = $state(0)

		increment() {
			this.count++ // 'this' might not be the Counter!
		}
	}

	let counter = new Counter()
</script>

<!-- AVOID:'this' will be the button, not the counter! -->
<button onclick={counter.increment}>
	Count: {counter.count}
</button>

Por qué sucede: En JavaScript, this se determina por cómo se llama a una función, no por dónde está definida. Cuando Svelte llama a counter.increment como manejador de eventos, this se convierte en el elemento botón.

Las soluciones:

<script>
	class Counter {
		count = $state(0)

		// Fix 1: Use arrow function in the class
		increment = () => {
			this.count++ // Arrow functions capture 'this'
		}

		// Fix 2: Regular method (needs wrapper in template)
		add() {
			this.count++
		}
	}

	let counter = new Counter()
</script>

<!-- Fix 1: Works directly -->
<button onclick={counter.increment}>Increment</button>

<!-- Fix 2: Wrap in arrow function -->
<button onclick={() => counter.add()}>Add</button>

Estado Superficial con `$state.raw`

¿Qué es `$state.raw`?

$state.raw crea estado reactivo que NO está profundamente proxificado. Los cambios a propiedades dentro del objeto/array no dispararán actualizaciones—solo la reasignación completa de la variable lo hará.

¿Cuándo Querría Usar Esto?

Analogía: Imagina que eres un bibliotecario con dos enfoques para rastrear libros:

Rastreo profundo ($state): Tienes un sensor en tiempo real en cada libro individual. Sabes en el instante en que cualquier libro es movido, abierto o tocado.
Rastreo superficial ($state.raw): Solo rastreas cuando estantes completos son reemplazados. No sabes si los libros individuales son movidos.

El rastreo profundo es preciso pero requiere más sensores (memoria/CPU). El rastreo superficial es más simple y rápido cuando solo te importan los cambios totales.

Cómo Usar `$state.raw`

<script>
	// Shallow reactive array
	let users = $state.raw([
		{ id: 1, name: 'Alice' },
		{ id: 2, name: 'Bob' }
	])

	// AVOID: This WON'T trigger an update
	function updateNameBroken() {
		users[0].name = 'Alicia' // No effect on UI!
	}

	// PREFERRED: This WILL trigger an update
	function updateNameWorks() {
		users = users.map((user) => (user.id === 1 ? { ...user, name: 'Alicia' } : user))
	}

	// PREFERRED: Replacing the entire array works
	async function fetchUsers() {
		users = await fetch('/api/users').then((r) => r.json())
	}
</script>

¿Por Qué Usar `$state.raw`?

A veces no necesitas reactividad profunda. Si siempre estás reemplazando el objeto/array completo y nunca lo mutás, $state.raw puede ser más eficiente. Evita la sobrecarga de crear Proxies para cada propiedad anidada. Veamos algunos escenarios específicos donde $state.raw puede ser beneficioso:

1: Rendimiento con Datos Grandes

El proxying profundo tiene una sobrecarga. Para arrays grandes (miles de elementos) que reemplazás por completo, $state.raw es más rápido.

<script>
	// Good candidate for $state.raw:
	// - Large dataset (thousands of rows)
	// - Data comes from an API (replaced entirely)
	// - You never mutate individual items
	let logEntries = $state.raw([])

	async function loadLogs() {
		// Replace the entire array with new data
		logEntries = await fetch('/api/logs').then((r) => r.json())
	}
</script>

2: Patrones de Datos Inmutables

Si seguís principios de datos inmutables (siempre creando nuevos objetos en lugar de mutarlos), $state.raw se adapta a ese estilo.

<script>
	let todos = $state.raw([])

	// Immutable add
	function addTodo(text) {
		todos = [...todos, { id: Date.now(), text, done: false }]
	}

	// Immutable toggle
	function toggleTodo(id) {
		todos = todos.map((todo) => (todo.id === id ? { ...todo, done: !todo.done } : todo))
	}

	// Immutable delete
	function deleteTodo(id) {
		todos = todos.filter((todo) => todo.id !== id)
	}
</script>

3: Integración con Librerías Externas

Algunas librerías esperan objetos simples, no Proxies. $state.raw te da datos sin proxificar.

`$state.raw` Puede Contener Estado Reactivo

Aquí hay un patrón poderoso: un array raw donde cada elemento es individualmente reactivo.

<script>
	// The array itself is raw (no proxy)
	let todos = $state.raw([])

	function addTodo(text) {
		// Each todo is individually reactive!
		const newTodo = $state({ text, done: false })

		// Must reassign the array (it's raw)
		todos = [...todos, newTodo]
	}
</script>

{#each todos as todo}
	<!-- Clicking this DOES work because todo itself is reactive -->
	<label>
		<input type="checkbox" bind:checked={todo.done} />
		{todo.text}
	</label>
{/each}

Esto te da lo mejor de ambos mundos:

Actualizaciones eficientes del array (solo reasignación)
Reactividad granular por elemento (cada todo se actualiza de forma independiente)

Usá $state.raw para arrays grandes (1000+ elementos) que reemplazás por completo. Es 3-5x más rápido porque omite el envoltorio de proxy profundo.

`$state.snapshot`: Obteniendo Objetos Simples

Cuando necesitás pasar un objeto reactivo a código que no espera Proxies (como JSON.stringify o librerías externas), usá $state.snapshot:

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

	function saveToServer() {
		// Get a plain object copy (no Proxy)
		const plainUser = $state.snapshot(user)

		// Now it's safe to use with external code
		fetch('/api/users', {
			method: 'POST',
			body: JSON.stringify(plainUser) // Works perfectly!
		})
	}

	function logUser() {
		// Logging a proxy shows "Proxy {}" which isn't helpful
		console.log(user) // Proxy { name: 'Alice', ... }

		// Snapshot gives you readable output
		console.log($state.snapshot(user)) // { name: 'Alice', preferences: { theme: 'dark' } }
	}
</script>

Consideraciones de Rendimiento

Cuándo la Reactividad Profunda Ayuda al Rendimiento

La reactividad profunda habilita actualizaciones granulares. Cuando cambiás una propiedad específica, solo los elementos de la UI que dependen de esa propiedad se vuelven a renderizar.

<script>
	let todos = $state([
		{ id: 1, text: 'First todo', done: false },
		{ id: 2, text: 'Second todo', done: false }
		// Imagine 1000 todos...
	])
</script>

{#each todos as todo}
	<!-- When todo.done changes, ONLY this checkbox re-renders -->
	<input type="checkbox" bind:checked={todo.done} />
{/each}

¡Sin reactividad profunda (o con un framework que no la tiene), cambiar un checkbox podría re-renderizar toda la lista!

Cuándo la Reactividad Profunda Perjudica el Rendimiento

El proxying profundo tiene una sobrecarga. Para conjuntos de datos muy grandes que reemplazás por completo (nunca mutás), esta sobrecarga es innecesaria.

<script>
	// AVOID:Suboptimal: Creating proxies for 10,000 objects we never mutate
	let rows = $state(await fetch('/api/large-dataset').then((r) => r.json()))

	// PREFERRED: Raw state for data we only replace
	let rows = $state.raw(await fetch('/api/large-dataset').then((r) => r.json()))
</script>

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

Usá `$state` cuando...	Usá `$state.raw` cuando...
Mutás propiedades individuales	Siempre reemplazás el valor completo
Los datos son interactivos para el usuario	Los datos provienen de una API
Datos de tamaño pequeño a mediano	Conjuntos de datos grandes (1000+ elementos)
Necesitás actualizaciones granulares	Solo necesitás actualizaciones totales

Ejemplos Prácticos

1: Carrito de Compras

Un carrito de compras completo que demuestra $state, $derived y reactividad basada en clases.

<script>
	// Product catalog
	let products = $state([
		{ id: 1, name: 'Laptop', price: 999, image: '💻' },
		{ id: 2, name: 'Headphones', price: 199, image: '🎧' },
		{ id: 3, name: 'Mouse', price: 49, image: '🖱️' },
		{ id: 4, name: 'Keyboard', price: 129, image: '⌨️' }
	])

	// Cart items: { productId, quantity }
	let cartItems = $state([])

	// Derived computations
	let cartWithDetails = $derived(
		cartItems.map((item) => {
			const product = products.find((p) => p.id === item.productId)
			return {
				...item,
				product,
				subtotal: product.price * item.quantity
			}
		})
	)

	let cartTotal = $derived(cartWithDetails.reduce((sum, item) => sum + item.subtotal, 0))

	let cartItemCount = $derived(cartItems.reduce((sum, item) => sum + item.quantity, 0))

	// Actions
	function addToCart(productId) {
		const existing = cartItems.find((item) => item.productId === productId)

		if (existing) {
			existing.quantity++
		} else {
			cartItems.push({ productId, quantity: 1 })
		}
	}

	function removeFromCart(productId) {
		const index = cartItems.findIndex((item) => item.productId === productId)
		if (index !== -1) {
			cartItems.splice(index, 1)
		}
	}

	function updateQuantity(productId, quantity) {
		const item = cartItems.find((item) => item.productId === productId)
		if (item) {
			if (quantity <= 0) {
				removeFromCart(productId)
			} else {
				item.quantity = quantity
			}
		}
	}
</script>

<div class="shop">
	<h2>Products</h2>
	<div class="products">
		{#each products as product}
			<div class="product">
				<span class="emoji">{product.image}</span>
				<h3>{product.name}</h3>
				<p>${product.price}</p>
				<button onclick={() => addToCart(product.id)}> Add to Cart </button>
			</div>
		{/each}
	</div>

	<h2>Cart ({cartItemCount} items)</h2>
	{#if cartItems.length === 0}
		<p>Your cart is empty</p>
	{:else}
		<ul class="cart">
			{#each cartWithDetails as item}
				<li>
					<span>{item.product.image} {item.product.name}</span>
					<input
						type="number"
						value={item.quantity}
						min="0"
						onchange={(e) => updateQuantity(item.productId, +e.target.value)}
					/>
					<span>${item.subtotal}</span>
					<button onclick={() => removeFromCart(item.productId)}>🗑️</button>
				</li>
			{/each}
		</ul>
		<p class="total"><strong>Total: ${cartTotal}</strong></p>
	{/if}
</div>

<style>
	.products {
		display: grid;
		grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
		gap: 1rem;
	}

	.product {
		border: 1px solid #ddd;
		padding: 1rem;
		border-radius: 8px;
		text-align: center;
	}

	.emoji {
		font-size: 2rem;
	}

	.cart li {
		display: flex;
		gap: 1rem;
		align-items: center;
		margin-bottom: 0.5rem;
	}

	.cart input {
		width: 60px;
	}
</style>

Conclusiones clave de este ejemplo:

La mutación funciona: cartItems.push(), item.quantity++ y splice() todos disparan actualizaciones
Cadenas derivadas: cartWithDetails depende de cartItems y products; cartTotal depende de cartWithDetails
Actualizaciones granulares: Cambiar la cantidad de un elemento solo recalcula lo necesario

2: Clase de Temporizador Reactivo

Este ejemplo muestra cómo usar correctamente $state y $derived dentro de una clase.

<script>
	class Stopwatch {
		// Reactive state fields
		milliseconds = $state(0)
		isRunning = $state(false)
		laps = $state([])

		// Private field for the interval
		#intervalId = null

		// Derived values
		formatted = $derived.by(() => {
			const ms = this.milliseconds
			const minutes = Math.floor(ms / 60000)
			const seconds = Math.floor((ms % 60000) / 1000)
			const centiseconds = Math.floor((ms % 1000) / 10)

			return `${minutes.toString().padStart(2, '0')}:${seconds.toString().padStart(2, '0')}.${centiseconds.toString().padStart(2, '0')}`
		})

		formattedLaps = $derived(
			this.laps.map((lapMs, index) => {
				const minutes = Math.floor(lapMs / 60000)
				const seconds = Math.floor((lapMs % 60000) / 1000)
				const centiseconds = Math.floor((lapMs % 1000) / 10)

				return {
					number: index + 1,
					time: `${minutes.toString().padStart(2, '0')}:${seconds.toString().padStart(2, '0')}.${centiseconds.toString().padStart(2, '0')}`
				}
			})
		)

		// Arrow functions to preserve 'this' binding
		start = () => {
			if (this.isRunning) return

			this.isRunning = true
			const startTime = Date.now() - this.milliseconds

			this.#intervalId = setInterval(() => {
				this.milliseconds = Date.now() - startTime
			}, 10)
		}

		stop = () => {
			if (!this.isRunning) return

			this.isRunning = false
			clearInterval(this.#intervalId)
		}

		reset = () => {
			this.stop()
			this.milliseconds = 0
			this.laps = []
		}

		lap = () => {
			if (!this.isRunning) return
			this.laps = [...this.laps, this.milliseconds]
		}

		toggle = () => {
			if (this.isRunning) {
				this.stop()
			} else {
				this.start()
			}
		}
	}

	let stopwatch = new Stopwatch()
</script>

<div class="stopwatch">
	<div class="display">{stopwatch.formatted}</div>

	<div class="controls">
		<button onclick={stopwatch.toggle}>
			{stopwatch.isRunning ? '⏸️ Pause' : '▶️ Start'}
		</button>

		<button onclick={stopwatch.lap} disabled={!stopwatch.isRunning}> 🏁 Lap </button>

		<button onclick={stopwatch.reset}> 🔄 Reset </button>
	</div>

	{#if stopwatch.laps.length > 0}
		<div class="laps">
			<h3>Laps</h3>
			<ol>
				{#each stopwatch.formattedLaps as lap}
					<li>Lap {lap.number}: {lap.time}</li>
				{/each}
			</ol>
		</div>
	{/if}
</div>

<style>
	.stopwatch {
		text-align: center;
		font-family: 'Courier New', monospace;
	}

	.display {
		font-size: 4rem;
		margin: 2rem 0;
	}

	.controls {
		display: flex;
		gap: 1rem;
		justify-content: center;
	}

	button {
		padding: 0.75rem 1.5rem;
		font-size: 1rem;
		border: none;
		border-radius: 4px;
		background: #3498db;
		color: white;
		cursor: pointer;
	}

	button:hover {
		background: #2980b9;
	}

	button:disabled {
		background: #bdc3c7;
		cursor: not-allowed;
	}

	.laps {
		margin-top: 2rem;
		text-align: left;
		max-width: 300px;
		margin-left: auto;
		margin-right: auto;
	}

	.laps ol {
		list-style-position: inside;
	}
</style>

Referencia Rápida

Creando Estado

// Primitive values
let count = $state(0)
let name = $state('Alice')
let active = $state(true)

// Objects (deeply reactive)
let user = $state({ name: 'Alice', age: 30 })

// Arrays (deeply reactive)
let items = $state([1, 2, 3])

// Raw (shallow reactive)
let data = $state.raw({ large: 'dataset' })

// Snapshot (get plain object)
const plain = $state.snapshot(user)

Usando Estado en Clases

class Counter {
	// Reactive field
	count = $state(0)

	// Arrow function to preserve 'this'
	increment = () => {
		this.count++
	}
}

Estado Compartido Entre Módulos

// state.svelte.js
export const store = $state({ count: 0 })

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

Puntos Clave

La runa $state es engañosamente simple en la superficie pero poderosa por debajo:

$state() hace los valores reactivos — Úsala para cualquier dato que deba disparar actualizaciones en la UI cuando cambie.
La reactividad profunda es automática — Los objetos y arrays se convierten en proxies profundamente reactivos. Las mutaciones en cualquier nivel disparan actualizaciones.
Saber cuándo la reactividad se rompe — La desestructuración, pasar primitivos a funciones y las instancias de clases son trampas comunes. Accede a las propiedades a través de los objetos reactivos.
$state.raw() para rendimiento — Úsalo para grandes conjuntos de datos que reemplazas en lugar de mutar.
Las clases necesitan $state() en sus campos — Coloca $state() en los campos que deben ser reactivos, no en la instancia de la clase.
Usa $state.snapshot() — Cuando necesites objetos planos para código externo o depuración.

Con estos patrones dominados, tendrás una base sólida para construir aplicaciones reactivas con Svelte 5.