Depurando Estado Reactivo Como un Profesional

Depurar aplicaciones reactivas puede ser frustrante. Las sentencias tradicionales de console.log solo te muestran una instantánea de tus datos en el momento en que las agregaste—no te dicen cuándo ni por qué cambian los valores. Terminas llenando tu código de logs, adivinando qué está pasando, y aun así perdiéndote los cambios de estado críticos que causan errores.

La rune $inspect de Svelte 5 resuelve este problema de manera elegante. Es como console.log con superpoderes: se vuelve a ejecutar automáticamente cada vez que cualquiera de sus valores rastreados cambia, te muestra exactamente qué cambió y cuándo, e incluso proporciona trazas de pila para identificar la fuente de las mutaciones de estado.

Este tutorial cubre todo, desde el uso básico hasta patrones avanzados de depuración, incluyendo el poderoso método de callback .with() y la rune $inspect.trace() para rastrear la ejecución de efectos.

¿Qué Es `$inspect`?

$inspect es una rune exclusiva para desarrollo que registra valores reactivos en la consola cada vez que cambian. A diferencia de console.log, que se ejecuta una sola vez, $inspect observa continuamente tus datos e informa cada mutación.

Uso Básico

Aquí está el ejemplo más simple:

<script>
	let count = $state(0)
	let message = $state('hello')

	$inspect(count, message) // Logs whenever count OR message changes
</script>

<button onclick={() => count++}>Increment</button>
<input bind:value={message} />

Qué sucede:

En el renderizado inicial, $inspect registra: init 0 "hello"
Clic en el botón → registra: update 1 "hello" (con traza de pila)
Escribir en el input → registra: update 1 "hello!" (con traza de pila)

La traza de pila es la característica clave—te muestra exactamente qué línea de código provocó el cambio de estado.

¿Por Qué Usar `$inspect` en Lugar de `console.log`?

`console.log`	`$inspect`
Se ejecuta una vez en esa línea	Se vuelve a ejecutar en cada cambio
Muestra el valor en ese momento	Muestra el valor cuando cambia
Sin contexto sobre qué lo activó	Incluye traza de pila hasta la fuente
Permanece en builds de producción	Se elimina automáticamente en producción
Inspección superficial	Rastreo reactivo profundo

Entendiendo la Salida

La salida de $inspect sigue un patrón predecible:

init <value1> <value2> ...     // First run (initialization)
update <value1> <value2> ...   // Subsequent runs (state changed)

Los valores se registran en el mismo orden en que los pasaste a $inspect.

Rastreo de Reactividad Profunda

Una de las características más poderosas de $inspect es el rastreo profundo. No solo observa variables de nivel superior—rastrea cambios en propiedades anidadas dentro de objetos y arreglos.

Rastreando Cambios en Objetos Anidados

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

	$inspect(user) // Tracks ALL nested changes
</script>

<button onclick={() => (user.name = 'Bob')}> Change Name </button>

<button onclick={() => (user.preferences.theme = 'light')}> Change Theme </button>

<button onclick={() => (user.preferences.notifications = false)}> Toggle Notifications </button>

Salida al hacer clic en cada botón:

init { name: 'Alice', preferences: { theme: 'dark', notifications: true } }
update { name: 'Bob', preferences: { theme: 'dark', notifications: true } }
update { name: 'Bob', preferences: { theme: 'light', notifications: true } }
update { name: 'Bob', preferences: { theme: 'light', notifications: false } }

Cada mutación anidada es capturada y registrada.

Rastreando Mutaciones de Arreglos

Los arreglos se rastrean con la misma precisión profunda:

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

	$inspect(todos)
</script>

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

<button onclick={() => (todos[0].done = true)}> Complete First </button>

<button onclick={() => todos.splice(0, 1)}> Remove First </button>

Cada push, splice, cambio de propiedad, u otra mutación activa el callback de inspección.

Observando Múltiples Valores

Puedes pasar múltiples valores para rastrearlos juntos:

<script>
	let firstName = $state('Alice')
	let lastName = $state('Chen')
	let age = $state(30)

	// Track all three in one inspect call
	$inspect(firstName, lastName, age)

	// Or use an object for labeled output
	$inspect({ firstName, lastName, age })
</script>

Salida etiquetada (usando un objeto):

init { firstName: 'Alice', lastName: 'Chen', age: 30 }
update { firstName: 'Alice', lastName: 'Smith', age: 30 }

Usar un objeto contenedor hace que la salida sea mucho más legible cuando se rastrean múltiples valores.

Callbacks Personalizados con `.with()`

El comportamiento predeterminado de console.log es útil, pero a veces necesitas más control. El método .with() te permite definir exactamente qué sucede cuando los valores cambian.

Uso Básico de `.with()`

<script>
	let count = $state(0)

	$inspect(count).with((type, count) => {
		if (type === 'init') {
			console.log('Count initialized to:', count)
		} else {
			console.log('Count updated to:', count)
		}
	})
</script>

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

El callback recibe:

type: Ya sea "init" (primera ejecución) o "update" (ejecuciones posteriores)
Argumentos restantes: Los valores que pasaste a $inspect, en orden

Activando el Depurador

Un patrón poderoso es activar el depurador del navegador ante cambios de estado:

<script>
	let criticalValue = $state(null)

	$inspect(criticalValue).with((type, value) => {
		if (type === 'update' && value === null) {
			// Something unexpectedly nullified our value!
			debugger // Pause execution here
		}
	})
</script>

Cuando el depurador se pausa, puedes examinar la pila de llamadas, las variables locales, y recorrer el código para entender qué ocurrió.

Traza de Consola para Pilas de Llamadas

Para información detallada de la pila de llamadas sin pausar la ejecución:

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

	$inspect(items).with((type, items) => {
		if (type === 'update') {
			console.trace('Items changed:', items.length, 'items')
		}
	})
</script>

console.trace() imprime la pila de llamadas junto con tu mensaje—perfecto para rastrear de dónde se originan las mutaciones.

Registro Condicional

Registra solo cuando se cumplen condiciones específicas:

<script>
	let formData = $state({
		email: '',
		password: '',
		confirmPassword: ''
	})

	$inspect(formData).with((type, data) => {
		// Only log password changes (be careful with sensitive data!)
		if (type === 'update') {
			if (data.password !== data.confirmPassword) {
				console.warn('Password mismatch detected')
			}
		}
	})
</script>

Registrar en Servicios Externos

Durante el desarrollo, es posible que quieras enviar cambios de estado a un servicio de registro externo:

<script>
	let appState = $state({
		/* ... */
	})

	$inspect(appState).with((type, state) => {
		// Send to development logging service
		fetch('/dev-api/log', {
			method: 'POST',
			headers: { 'Content-Type': 'application/json' },
			body: JSON.stringify({
				type,
				state: $state.snapshot(state),
				timestamp: Date.now()
			})
		})
	})
</script>

Conteo de Actualizaciones

Rastrea cuántas veces cambia un valor:

<script>
	let data = $state({
		/* ... */
	})
	let updateCount = 0

	$inspect(data).with((type) => {
		if (type === 'update') {
			updateCount++
			console.log(`Update #${updateCount}`)
		}
	})
</script>

Este patrón ayuda a identificar re-renderizados excesivos o una frecuencia de actualización inesperada.

Rastreo de Funciones con `$inspect.trace()`

Agregado en Svelte 5.14, $inspect.trace() es una herramienta especializada para entender por qué los efectos y los valores derivados se vuelven a ejecutar. En lugar de observar valores específicos, rastrea las dependencias reactivas de la función que lo rodea.

Uso Básico de `$inspect.trace()`

<script>
	let firstName = $state('Alice')
	let lastName = $state('Chen')
	let age = $state(30)

	$effect(() => {
		$inspect.trace() // Must be the FIRST statement

		console.log(`${firstName} ${lastName} is ${age} years old`)
	})
</script>

<button onclick={() => (firstName = 'Bob')}>Change First Name</button>
<button onclick={() => (lastName = 'Smith')}>Change Last Name</button>
<button onclick={() => age++}>Increment Age</button>

Cuando haces clic en "Change First Name", la consola muestra:

<effect> — $effect {
  firstName: 'Alice' -> 'Bob'
}

Esto te indica exactamente qué dependencia reactiva disparó la re-ejecución del efecto.

Agregar Etiquetas para Mayor Claridad

Cuando tienes múltiples efectos, las etiquetas ayudan a identificar cuál está ejecutándose:

<script>
	let x = $state(0)
	let y = $state(0)

	$effect(() => {
		$inspect.trace('Position Effect')
		updatePosition(x, y)
	})

	$effect(() => {
		$inspect.trace('Validation Effect')
		validateCoordinates(x, y)
	})
</script>

Salida:

Position Effect — $effect {
  x: 0 -> 1
}
Validation Effect — $effect {
  x: 0 -> 1
}

Rastreo de Valores Derivados

$inspect.trace() también funciona dentro de $derived.by():

<script>
	let items = $state([
		{ name: 'Apple', price: 1.5, quantity: 3 },
		{ name: 'Banana', price: 0.75, quantity: 5 }
	])
	let taxRate = $state(0.08)

	let total = $derived.by(() => {
		$inspect.trace('Total Calculation')

		const subtotal = items.reduce((sum, item) => sum + item.price * item.quantity, 0)
		return subtotal * (1 + taxRate)
	})
</script>

Cuando cambia taxRate:

Total Calculation — $derived {
  taxRate: 0.08 -> 0.10
}

Cuando cambia el precio de un artículo:

Total Calculation — $derived {
  items[0].price: 1.5 -> 2
}

Importante: Reglas de Posicionamiento

$inspect.trace() solo funciona cuando es la primera línea del cuerpo de la función. Si cualquier otra declaración se ejecuta antes — incluso una declaración de variable — Svelte no puede configurar el rastreo correctamente y arrojará un error.

$inspect.trace() debe ser la primera declaración en el cuerpo de la función:

<script>
	$effect(() => {
		$inspect.trace() // PREFERRED: first statement

		// ... rest of the effect
	})

	$effect(() => {
		const something = 'value'
		$inspect.trace() // AVOID: not the first statement
	})
</script>

Patrones de Depuración en el Mundo Real

Patrón 1: Depuración del Estado de Formulario

Depura el estado complejo de un formulario con validación:

<script>
	let form = $state({
		email: '',
		password: '',
		confirmPassword: '',
		acceptTerms: false
	})

	let errors = $state({
		email: null,
		password: null,
		confirmPassword: null,
		acceptTerms: null
	})

	let touched = $state({
		email: false,
		password: false,
		confirmPassword: false,
		acceptTerms: false
	})

	// Debug the entire form state
	$inspect({ form, errors, touched }).with((type, data) => {
		if (type === 'update') {
			console.group('Form State Change')
			console.log('Form:', data.form)
			console.log('Errors:', data.errors)
			console.log('Touched:', data.touched)
			console.groupEnd()
		}
	})

	// Validate on changes
	$effect(() => {
		$inspect.trace('Validation Effect')

		// Email validation
		if (touched.email) {
			errors.email = !form.email.includes('@') ? 'Invalid email' : null
		}

		// Password validation
		if (touched.password) {
			errors.password = form.password.length < 8 ? 'Password must be at least 8 characters' : null
		}

		// Confirm password validation
		if (touched.confirmPassword) {
			errors.confirmPassword =
				form.password !== form.confirmPassword ? 'Passwords do not match' : null
		}
	})
</script>

Patrón 2: Máquina de Estado de Solicitudes API

Rastrea el ciclo de vida completo de las operaciones asíncronas:

<script>
	let requestState = $state({
		status: 'idle', // 'idle' | 'loading' | 'success' | 'error'
		data: null,
		error: null,
		lastFetchedAt: null
	})

	$inspect(requestState).with((type, state) => {
		const statusEmoji = {
			idle: '⏸️',
			loading: '⏳',
			success: '✅',
			error: '❌'
		}

		console.log(
			`${statusEmoji[state.status]} Request state: ${state.status}`,
			state.data ? `(${JSON.stringify(state.data).slice(0, 50)}...)` : ''
		)

		if (state.status === 'error') {
			console.error('Request failed:', state.error)
		}
	})

	async function fetchData() {
		requestState.status = 'loading'
		requestState.error = null

		try {
			const response = await fetch('/api/data')
			if (!response.ok) error(`HTTP ${response.status}`)

			requestState.data = await response.json()
			requestState.status = 'success'
			requestState.lastFetchedAt = new Date().toISOString()
		} catch (error) {
			requestState.error = error.message
			requestState.status = 'error'
		}
	}
</script>

Patrón 3: Depuración del Carrito de Compras

Rastrea cada mutación en un carrito de compras:

<script>
	let cart = $state({
		items: [],
		couponCode: null,
		discountApplied: false
	})

	$inspect(cart).with((type, cart) => {
		if (type === 'init') {
			console.log('🛒 Cart initialized')
			return
		}

		const itemCount = cart.items.reduce((sum, item) => sum + item.quantity, 0)
		const total = cart.items.reduce((sum, item) => sum + item.price * item.quantity, 0)

		console.log(`🛒 Cart updated:
  Items: ${itemCount}
  Total: $${total.toFixed(2)}
  Coupon: ${cart.couponCode || 'none'}
  Discount: ${cart.discountApplied ? 'applied' : 'not applied'}`)
	})

	function addItem(product) {
		const existing = cart.items.find((item) => item.id === product.id)

		if (existing) {
			existing.quantity++
		} else {
			cart.items.push({ ...product, quantity: 1 })
		}
	}

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

	function applyCoupon(code) {
		cart.couponCode = code
		cart.discountApplied = code === 'SAVE20'
	}
</script>

Patrón 4: Depuración del Ciclo de Vida de Componentes

Comprende el comportamiento de montaje/desmontaje de los componentes:

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

	let { userId } = $props()

	let componentState = $state({
		mounted: false,
		dataLoaded: false,
		renderCount: 0
	})

	$inspect({ userId, componentState }).with((type, data) => {
		console.log(`[User ${data.userId}] ${type}:`, data.componentState)
	})

	onMount(() => {
		componentState.mounted = true
		console.log(`[User ${userId}] Component mounted`)
	})

	onDestroy(() => {
		console.log(`[User ${userId}] Component destroying`)
	})

	$effect(() => {
		componentState.renderCount++
	})
</script>

Patrón 5: Depuración de Cadena de Valores Derivados

Rastrea cómo se propagan los valores derivados:

<script>
	let basePrice = $state(100)
	let quantity = $state(1)
	let taxRate = $state(0.08)
	let discountPercent = $state(0)

	let subtotal = $derived.by(() => {
		$inspect.trace('Subtotal')
		return basePrice * quantity
	})

	let discount = $derived.by(() => {
		$inspect.trace('Discount')
		return subtotal * (discountPercent / 100)
	})

	let taxableAmount = $derived.by(() => {
		$inspect.trace('Taxable Amount')
		return subtotal - discount
	})

	let tax = $derived.by(() => {
		$inspect.trace('Tax')
		return taxableAmount * taxRate
	})

	let total = $derived.by(() => {
		$inspect.trace('Total')
		return taxableAmount + tax
	})

	// Also log the final values
	$inspect({ subtotal, discount, taxableAmount, tax, total })
</script>

Cuando cambias quantity, verás toda la cascada:

Subtotal — $derived { quantity: 1 -> 2 }
Discount — $derived { subtotal: 100 -> 200 }
Taxable Amount — $derived { subtotal: 100 -> 200, discount: 0 -> 0 }
Tax — $derived { taxableAmount: 100 -> 200 }
Total — $derived { taxableAmount: 100 -> 200, tax: 8 -> 16 }

Errores Comunes y Soluciones

Error 1: Olvidar que Es Solo para Desarrollo

$inspect se elimina de las compilaciones de producción, por lo que no hay costo en tiempo de ejecución en producción. Sin embargo, registra valores en la consola durante el desarrollo y la preparación — incluyendo cualquier dato que le pases. Trátalo como una declaración debugger: elimínalo antes de que llegue a un entorno compartido.

$inspect se elimina automáticamente en las compilaciones de producción. No dependas de él para el registro en producción.

<script>
	let data = $state(null)

	// AVOID: Won't work in production
	$inspect(data).with((type, data) => {
		sendToAnalytics(data) // This never runs in production!
	})

	// PREFERRED: Use a proper logging solution for production
	$effect(() => {
		if (import.meta.env.DEV) {
			console.log('Data changed:', data)
		}
		// Production logging handled elsewhere
	})
</script>

Error 2: Inspect en un Ámbito Incorrecto

$inspect debe estar en un contexto reactivo (script de componente, archivo .svelte.js, o efecto):

<script>
	let count = $state(0)

	// PREFERRED: top-level of component script
	$inspect(count)

	function handleClick() {
		// AVOID: Doesn't work: inside regular function
		$inspect(count) // This won't track changes!

		count++
	}
</script>

Error Común 3: Demasiadas Llamadas a $inspect

El exceso de llamadas a $inspect puede saturar tu consola:

<script>
	let items = $state([
		/* 1000 items */
	])

	// AVOID: Logs on EVERY nested change
	$inspect(items)

	// PREFERRED: inspect specific things
	$inspect(items.length) // Only track array length

	// PREFERRED: use conditional logging
	$inspect(items).with((type, items) => {
		if (items.length > 100) {
			console.warn('Large array detected:', items.length)
		}
	})
</script>

Error Común 4: Olvidar la Ubicación de $inspect.trace()

$inspect.trace() debe ser la primera instrucción:

<script>
	$effect(() => {
		// AVOID: something before $inspect.trace()
		const now = Date.now()
		$inspect.trace()
	})

	$effect(() => {
		// PREFERRED: $inspect.trace() is first
		$inspect.trace()
		const now = Date.now()
	})
</script>

Error Común 5: Registrar Objetos Proxied

Los objetos reactivos son Proxies, lo que puede verse confuso en la consola:

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

	// Console might show: Proxy { name: 'Alice' }
	$inspect(user)

	// PREFERRED: For cleaner output, use $state.snapshot
	$inspect($state.snapshot(user))
</script>

Error Común 6: Bucles Infinitos con .with()

Escribir en una variable $state dentro de un callback .with() activará el grafo reactivo, que vuelve a ejecutar $inspect, que llama a .with() nuevamente — un bucle infinito. Usá variables simples (no reactivas) para cualquier acumulación que necesites dentro del callback.

Ten cuidado de no disparar cambios de estado dentro de .with():

<script>
	let count = $state(0)
	let history = $state([])

	// AVOID: Danger: This creates an infinite loop!
	$inspect(count).with((type, count) => {
		history.push(count) // Mutates state -> triggers inspect -> mutates state...
	})

	// PREFERRED: Safe: Track count changes without mutating reactive state
	let historyArray = [] // Non-reactive
	$inspect(count).with((type, count) => {
		historyArray.push(count)
		console.log('History:', historyArray)
	})
</script>

Consideraciones de Rendimiento

`$inspect` No Tiene Costo en Producción

El compilador de Svelte elimina completamente las llamadas a $inspect en las compilaciones de producción. No hay sobrecarga en tiempo de ejecución — es como si el código nunca hubiera existido.

// Development build includes $inspect
$inspect(count)

// Production build: the line is gone entirely

El Seguimiento Profundo Tiene Sobrecarga en Desarrollo

Si bien $inspect es gratuito en producción, el seguimiento profundo sí tiene sobrecarga en desarrollo. Para estructuras de datos muy grandes, considera:

Inspeccionar propiedades específicas en lugar de objetos enteros
Usar callbacks condicionales que solo registren cuando sea necesario
Eliminar las llamadas a inspect cuando no estés depurando activamente

<script>
	let hugeDataset = $state([
		/* thousands of items */
	])

	// AVOID: Heavy: tracks every nested change
	$inspect(hugeDataset)

	// PREFERRED: Lighter: only track length
	$inspect(hugeDataset.length)

	// PREFERRED: conditional logging
	$inspect(hugeDataset).with((type, data) => {
		// Only log every 10th update
		if (Math.random() < 0.1) {
			console.log('Sample update:', data.slice(0, 5))
		}
	})
</script>

Integración con las DevTools del Navegador

Aprovechando el Stack Trace

Por defecto, las actualizaciones de $inspect incluyen un stack trace. Hacé clic en el trace en la consola de tu navegador para saltar directamente al código que disparó el cambio.

Usando la Instrucción `debugger`

Pausá la ejecución exactamente cuando cambia el estado:

<script>
	let criticalValue = $state('normal')

	$inspect(criticalValue).with((type, value) => {
		if (value === 'error') {
			debugger // Execution pauses here
		}
	})
</script>

Cuando esté pausado, podés:

Examinar el call stack
Inspeccionar variables locales y globales
Recorrer el código línea por línea
Establecer expresiones de seguimiento

Filtrado en la Consola

Usá grupos y etiquetas de consola para filtrar la salida de $inspect:

<script>
	let auth = $state({ user: null, token: null })
	let ui = $state({ theme: 'dark', sidebar: true })

	$inspect(auth).with((type, auth) => {
		console.groupCollapsed('[Auth]', type)
		console.log(auth)
		console.groupEnd()
	})

	$inspect(ui).with((type, ui) => {
		console.groupCollapsed('[UI]', type)
		console.log(ui)
		console.groupEnd()
	})
</script>

Ahora podés colapsar/expandir diferentes categorías en la consola.

Referencia Rápida

Inspect Básico

// Single value
$inspect(count)

// Multiple values
$inspect(count, name, items)

// Object for labeled output
$inspect({ count, name, items })

Callback Personalizado

$inspect(value).with((type, value) => {
	// type is 'init' or 'update'
	// value is the current value

	console.log(type, value)
	// or: debugger
	// or: console.trace()
	// or: custom logic
})

Trazado de Funciones

$effect(() => {
	$inspect.trace() // No label
	// ... effect code
})

$effect(() => {
	$inspect.trace('My Effect Label') // With label
	// ... effect code
})

let value = $derived.by(() => {
	$inspect.trace('Derived Calculation')
	return computeValue()
})

Patrones Comunes

// Trigger debugger on specific condition
$inspect(value).with((type, v) => {
	if (v === problematicValue) debugger
})

// Count updates
let updates = 0
$inspect(value).with((type) => {
	if (type === 'update') console.log(`Update #${++updates}`)
})

// Log with timestamp
$inspect(value).with((type, v) => {
	console.log(`[${new Date().toISOString()}]`, type, v)
})

// Grouped logging
$inspect(value).with((type, v) => {
	console.group(`State ${type}`)
	console.log(v)
	console.trace()
	console.groupEnd()
})

Conclusiones Clave

La runa $inspect transforma la depuración de adivinanzas en precisión:

$inspect(values) observa el estado reactivo — Registra automáticamente cada vez que cambia cualquier valor rastreado, con soporte de reactividad profunda.
.with() personaliza el callback — Reemplazá el console.log predeterminado con cualquier lógica: instrucciones debugger, registro condicional o formato personalizado.
$inspect.trace() traza las dependencias — Mirá exactamente qué valores reactivos causaron que un efecto o derivado se vuelva a ejecutar.
Cero sobrecarga en producción — $inspect se elimina completamente de las compilaciones de producción.

Eliminá las llamadas a $inspect antes de hacer commit a main. El compilador las elimina de las compilaciones de producción, por lo que no hay sobrecarga en tiempo de ejecución — pero dejarlas en el código fuente significa que los valores sensibles se registran durante el desarrollo y el staging, lo que representa un riesgo de exposición de datos.

El seguimiento profundo captura todo — Las mutaciones de objetos anidados y arreglos se detectan automáticamente.
Los stack traces identifican las fuentes — Hacé clic para ir a la línea exacta que disparó el cambio de estado.

Con estas herramientas, pasarás menos tiempo buscando errores y más tiempo desarrollando funcionalidades. La experiencia de depuración reactiva en Svelte 5 es genuinamente placentera una vez que la dominás.