Depurando Estado Reativo Como um Profissional

Depurar aplicações reativas pode ser frustrante. Instruções tradicionais de console.log mostram apenas um instantâneo dos seus dados no momento em que foram adicionadas — elas não informam quando ou por que os valores mudam. Você acaba enchendo seu código de logs, tentando adivinhar o que está acontecendo e ainda perdendo as mudanças críticas de estado que causam bugs.

A rune $inspect do Svelte 5 resolve esse problema com elegância. É como console.log com superpoderes: ela é executada automaticamente sempre que qualquer um dos valores rastreados muda, mostra exatamente o que mudou e quando, e ainda fornece stack traces para identificar com precisão a origem das mutações de estado.

Este tutorial abrange tudo, desde o uso básico até padrões avançados de depuração, incluindo o poderoso método de callback .with() e a rune $inspect.trace() para rastrear a execução de efeitos.

O Que É `$inspect`?

$inspect é uma rune exclusiva para desenvolvimento que registra valores reativos no console sempre que eles mudam. Ao contrário de console.log, que é executado uma única vez, $inspect monitora continuamente seus dados e reporta cada mutação.

Uso Básico

Aqui está o exemplo mais simples:

<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} />

O que acontece:

Na renderização inicial, $inspect registra: init 0 "hello"
Clique no botão → registra: update 1 "hello" (com stack trace)
Digite no campo → registra: update 1 "hello!" (com stack trace)

O stack trace é o recurso matador — ele mostra exatamente qual linha de código acionou a mudança de estado.

Por Que Usar `$inspect` em Vez de `console.log`?

`console.log`	`$inspect`
Executa uma vez naquela linha	Re-executa a cada mudança
Mostra o valor naquele momento	Mostra o valor quando ele muda
Sem contexto sobre o que o acionou	Inclui stack trace até a origem
Permanece em builds de produção	Removido automaticamente em produção
Inspeção superficial	Rastreamento reativo profundo

Entendendo a Saída

A saída do $inspect segue um padrão previsível:

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

Os valores são registrados na mesma ordem em que foram passados para $inspect.

Rastreamento Reativo Profundo

Um dos recursos mais poderosos do $inspect é o rastreamento profundo. Ele não apenas observa variáveis de nível superior — ele rastreia mudanças em propriedades aninhadas dentro de objetos e arrays.

Rastreando Mudanças em Objetos Aninhados

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

Saída ao clicar em cada botão:

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 mutação aninhada é capturada e registrada.

Rastreando Mutações em Arrays

Arrays são rastreados com a mesma precisão 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>

Todo push, splice, mudança de propriedade ou outra mutação aciona o callback de inspeção.

Observando Múltiplos Valores

Você pode passar múltiplos valores para rastreá-los 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>

Saída rotulada (usando um objeto):

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

Usar um objeto como wrapper torna a saída muito mais legível ao rastrear múltiplos valores.

Callbacks Personalizados com `.with()`

O comportamento padrão de console.log é útil, mas às vezes você precisa de mais controle. O método .with() permite definir exatamente o que acontece quando os valores mudam.

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>

O callback recebe:

type: Pode ser "init" (primeira execução) ou "update" (execuções subsequentes)
Argumentos restantes: Os valores que você passou para $inspect, em ordem

Acionando o Depurador

Um padrão poderoso é acionar o depurador do navegador em mudanças 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>

Quando o depurador pausar, você pode examinar a pilha de chamadas, variáveis locais e percorrer o código para entender o que aconteceu.

Console Trace para Pilhas de Chamadas

Para informações detalhadas da pilha de chamadas sem pausar a execução:

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

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

console.trace() imprime a pilha de chamadas junto com sua mensagem — perfeito para rastrear onde as mutações se originam.

Log Condicional

Registre apenas quando condições específicas forem atendidas:

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

Registrando em Serviços Externos

Durante o desenvolvimento, você pode querer enviar mudanças de estado para um serviço 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>

Contando Atualizações

Rastreie quantas vezes um valor muda:

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

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

Este padrão ajuda a identificar re-renderizações excessivas ou frequência de atualização inesperada.

Rastreamento de Funções com `$inspect.trace()`

Adicionado no Svelte 5.14, $inspect.trace() é uma ferramenta especializada para entender por que efeitos e valores derivados são re-executados. Em vez de observar valores específicos, ele rastreia as dependências reativas da função ao redor.

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>

Quando você clica em "Change First Name", o console exibe:

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

Isso informa exatamente qual dependência reativa acionou a re-execução do efeito.

Adicionando Rótulos para Maior Clareza

Quando você tem múltiplos efeitos, rótulos ajudam a identificar qual está sendo executado:

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

Saída:

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

Rastreando Valores Derivados

$inspect.trace() também 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>

Quando taxRate muda:

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

Quando o preço de um item muda:

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

Importante: Regras de Posicionamento

$inspect.trace() só funciona quando é a primeira linha do corpo da função. Se qualquer outra instrução for executada antes — mesmo uma declaração de variável — o Svelte não consegue configurar o rastreamento corretamente e lançará um erro.

$inspect.trace() deve ser a primeira instrução no corpo da função:

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

		// ... rest of the effect
	})

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

Padrões de Depuração do Mundo Real

Padrão 1: Depuração de Estado de Formulário

Depure estados complexos de formulário com validação:

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

Padrão 2: Máquina de Estado de Requisição de API

Rastreie o ciclo de vida completo de operações assí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>

Padrão 3: Depuração de Carrinho de Compras

Rastreie cada mutação em um carrinho 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>

Padrão 4: Depuração do Ciclo de Vida do Componente

Entenda o comportamento de montagem/desmontagem de 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>

Padrão 5: Depuração de Cadeia de Valores Derivados

Rastreie como valores derivados se propagam em cascata:

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

Quando você muda quantity, você verá a cascata completa:

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 }

Armadilhas Comuns e Soluções

Armadilha 1: Esquecer que É Apenas para Desenvolvimento

$inspect é removido dos builds de produção, portanto não há custo em tempo de execução em produção. No entanto, ele registra valores no console durante o desenvolvimento e staging — incluindo quaisquer dados que você passar para ele. Trate-o como uma instrução debugger: remova-o antes que chegue a um ambiente compartilhado.

$inspect é automaticamente removido em builds de produção. Não dependa dele para registro em produção.

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

Armadilha 2: Inspect no Escopo Errado

$inspect deve estar em um contexto reativo (script de componente, arquivo .svelte.js ou efeito):

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

Armadilha 3: Excesso de Chamadas $inspect

Chamadas excessivas de $inspect podem inundar seu console:

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

Armadilha 4: Esquecendo o Posicionamento de $inspect.trace()

$inspect.trace() deve ser a primeira instrução:

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

Armadilha 5: Registrando Objetos Proxiados

Objetos reativos são Proxies, o que pode parecer confuso no console:

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

Armadilha 6: Loops Infinitos com .with()

Escrever em uma variável $state dentro de um callback .with() vai acionar o grafo reativo, que reexecuta $inspect, que chama .with() novamente — um loop infinito. Use variáveis simples (não reativas) para qualquer acumulação necessária dentro do callback.

Tenha cuidado para não acionar mudanças 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>

Considerações de Desempenho

`$inspect` Tem Custo Zero em Produção

O compilador do Svelte remove completamente as chamadas de $inspect nos builds de produção. Não há sobrecarga em tempo de execução — é como se o código nunca tivesse existido.

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

// Production build: the line is gone entirely

O Rastreamento Profundo Tem Sobrecarga no Desenvolvimento

Embora $inspect seja gratuito em produção, o rastreamento profundo tem sobrecarga no desenvolvimento. Para estruturas de dados muito grandes, considere:

Inspecionar propriedades específicas em vez de objetos inteiros
Usar callbacks condicionais que registram apenas quando necessário
Remover chamadas de inspect quando não estiver depurando ativamente

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

Integração com o DevTools do Navegador

Aproveitando o Stack Trace

Por padrão, as atualizações de $inspect incluem um stack trace. Clique no trace no console do seu navegador para ir diretamente ao código que acionou a mudança.

Usando a Instrução `debugger`

Pause a execução exatamente quando o estado muda:

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

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

Quando pausado, você pode:

Examinar a pilha de chamadas
Inspecionar variáveis locais e globais
Percorrer o código linha por linha
Definir expressões de observação

Filtragem no Console

Use grupos e rótulos no console para filtrar a saída 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>

Agora você pode recolher/expandir diferentes categorias no console.

Referência 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
})

Rastreamento de Função

$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()
})

Padrões Comuns

// 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()
})

Principais Conclusões

A rune $inspect transforma a depuração de adivinhação em precisão:

$inspect(values) observa o estado reativo — Registra automaticamente sempre que qualquer valor rastreado muda, com suporte a reatividade profunda.
.with() personaliza o callback — Substitua o console.log padrão por qualquer lógica: instruções debugger, registro condicional ou formatação personalizada.
$inspect.trace() rastreia dependências — Veja exatamente quais valores reativos causaram a reexecução de um efeito ou derivado.
Zero sobrecarga em produção — $inspect é completamente removido dos builds de produção.

Remova as chamadas de $inspect antes de fazer commit na branch principal. O compilador as remove dos builds de produção, portanto não há sobrecarga em tempo de execução — mas deixá-las no código-fonte significa que valores sensíveis são registrados durante o desenvolvimento e staging, o que representa um risco de exposição de dados.

O rastreamento profundo captura tudo — Mutações em objetos aninhados e arrays são detectadas automaticamente.
Os stack traces identificam as origens — Clique para ir até a linha exata que acionou a mudança de estado.

Com essas ferramentas, você gastará menos tempo caçando bugs e mais tempo criando funcionalidades. A experiência de depuração reativa no Svelte 5 é genuinamente deliciosa quando você a domina.