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 activa automáticamente actualizaciones de la UI cuando cambia. A diferencia de otros frameworks que requieren objetos envolventes o funciones setter, Svelte te permite trabajar con valores reactivos como si fueran 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ánica de proxies, optimización de rendimiento con $state.raw, y los errores comunes que tropiezan 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 utilice.

Uso Básico

Aquí está el ejemplo más simple posible:

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

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

Analicemos esto parte por parte:

let count = $state(0) - Crea una variable reactiva llamada count con un valor inicial de 0
onclick={() => count++} - Al hacer 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 a Otros Frameworks

Si has usado React, Vue u otros frameworks, puede 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 vanilla.

Cómo Funciona Internamente (Simplificado)

Cuando escribes let count = $state(0), el compilador de Svelte transforma tu código. Aquí hay 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 archivos .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 clases	`class Counter { count = $state(0) }`

No puedes usar $state en:

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

Preguntas Frecuentes para 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 de los Proxies

¿Qué Es la Reactividad Profunda?

Cuando pasas un objeto o arreglo a $state, ocurre algo especial: Svelte lo hace profundamente reactivo. Esto significa que los cambios en propiedades anidadas (sin importar qué tan profundas sean) activan automáticamente actualizaciones de 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 normales), solo vigilas la puerta principal. Si alguien entra por una ventana o puerta trasera, no te das cuenta.

Con monitoreo profundo (objetos/arreglos con $state), tienes cámaras en cada habitación, cada pasillo, cada armario. Cualquier cambio en cualquier parte del edificio dispara 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 toda la página!)

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 sorprendente aquí:

Los métodos de arreglo funcionan: todos.push() activa una actualización. También lo hacen pop(), splice(), shift(), etc.
Los objetos anidados son reactivos: Cambiar todo.done actualiza solo ese checkbox
Los nuevos elementos se vuelven reactivos: Cuando haces push de un nuevo objeto, automáticamente se vuelve reactivo también
Actualizaciones granulares: Marcar un checkbox 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 entero.

Qué Se Proxifica (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 el que los Proxies podrían interferir. Los objetos nativos como Map y Set tienen slots internos a los que los Proxies no pueden acceder.

Clases Nativas 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 proporciona 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 igual que sus contrapartes nativas pero son totalmente reactivas.

Cuándo la Reactividad Se Rompe

Entender cuándo la reactividad no funciona es tan importante como 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 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. Desestructurar 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 es ahora solo una variable regular 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 de Paso por Valor)

Qué sucede: JavaScript pasa valores, no referencias. Cuando pasas un valor $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 de forma verbal. Si luego cambias tu número de teléfono, ellos todavía tienen 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 a 1
y se evalúa a 2
La función recibe los valores 1 y 2
Retorna 3
total se establece en 3

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

La solución: Usa $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 Proxifican

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 suelen tener métodos, getters, setters y lógica interna con la que los Proxies podrían interferir. Svelte actúa con precaución y no las proxifica.

La solución: Usa $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>

Idea clave: Coloca $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. Exporta un objeto y muta sus propiedades en su lugar — 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 del Binding de `this` en las Clases

Qué sucede: Cuando pasas un método de una clase como controlador 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 está determinado por cómo se llama una función, no por dónde está definida. Cuando Svelte llama a counter.increment como controlador de eventos, this se convierte en el elemento button.

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 en las propiedades dentro del objeto/array no dispararán actualizaciones—solo la reasignación de la variable completa lo hará.

¿Cuándo querrías 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 al instante si cualquier libro es movido, abierto o tocado.
Rastreo superficial ($state.raw): Solo rastreas cuando estantes enteros son reemplazados. No sabes si los libros individuales se mueven.

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

La proxificación profunda tiene una sobrecarga. Para arrays grandes (miles de elementos) que reemplazás en su totalidad, $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 sin proxy 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 tarea se actualiza de forma independiente)

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

`$state.snapshot`: Obtener 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 mejora el rendimiento

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

<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 una casilla de verificación podría volver a renderizar toda la lista!

Cuándo la reactividad profunda perjudica el rendimiento

La proxificación profunda 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>

Puntos clave de este ejemplo:

La mutación funciona: cartItems.push(), item.quantity++ y splice() 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

Crear 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)

Usar 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++
}

Conclusiones Clave

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

$state() hace que los valores sean reactivos — Úsalo para cualquier dato que deba desencadenar 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 desencadenan actualizaciones.
Conoce cuándo se rompe la reactividad — La desestructuración, pasar primitivos a funciones e instancias de clases son errores comunes. Accede a las propiedades a través de objetos reactivos.
$state.raw() para rendimiento — Úsalo para grandes conjuntos de datos que reemplazas en lugar de mutar.
Las clases necesitan $state() en los campos — Coloca $state() en los campos que deben ser reactivos, no en la instancia de la clase.
Usa $state.snapshot() — Cuando necesites objetos simples para código externo o depuración.

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