Depuração Reativa no Nível do Template

Na intrincada dança do gerenciamento de estado reativo, entender quando e por que os valores mudam pode ser a diferença entre uma resolução rápida de problemas e horas de frustração. A tag @debug do Svelte 5 oferece uma abordagem declarativa para depuração que se integra perfeitamente ao modelo reativo do framework, fornecendo insights em tempo real sobre mutações de estado à medida que ocorrem.

Ao contrário das abordagens tradicionais de depuração que exigem instruções console.log manuais espalhadas pelo código ou configurações elaboradas de breakpoints, a tag @debug opera reativamente — registrando automaticamente os valores sempre que qualquer dependência rastreada muda. Isso a torna uma ferramenta inestimável para entender fluxos reativos complexos, rastrear bugs difíceis de encontrar e obter uma compreensão mais profunda de como o estado do seu componente evolui ao longo do tempo.

Entender quando empregar o @debug, o que rastrear e como interpretar sua saída o transforma de um simples mecanismo de registro em uma poderosa ferramenta de diagnóstico capaz de iluminar até os padrões reativos mais intrincados.

O Problema

O Desafio da Depuração

Considere um cenário em que você está construindo um configurador de produtos para e-commerce. Múltiplos estados interagem para determinar o preço final, e você está enfrentando resultados de cálculo inesperados:

<script>
	let basePrice = $state(100)
	let quantity = $state(1)
	let discountCode = $state('')
	let memberDiscount = $state(false)

	let subtotal = $derived(basePrice * quantity)
	let codeDiscount = $derived(discountCode === 'SAVE20' ? 0.2 : 0)
	let membershipDiscount = $derived(memberDiscount ? 0.1 : 0)
	let totalDiscount = $derived(codeDiscount + membershipDiscount)
	let finalPrice = $derived(subtotal * (1 - totalDiscount))
</script>

<div class="configurator">
	<label>
		Quantity: <input type="number" bind:value={quantity} min="1" />
	</label>

	<label>
		Discount Code: <input bind:value={discountCode} />
	</label>

	<label>
		<input type="checkbox" bind:checked={memberDiscount} />
		Member Discount
	</label>

	<div class="price">
		Final Price: ${finalPrice.toFixed(2)}
	</div>
</div>

Quando o cálculo do preço parece incorreto, você precisa entender quais valores estão mudando e quando. A depuração tradicional requer a inserção de múltiplas instruções console.log, sua remoção posterior e a possibilidade de não identificar qual cadeia reativa acionou a atualização.

A Solução com `@debug`

A tag @debug fornece registro reativo que dispara automaticamente sempre que os valores rastreados mudam:

<script>
	let basePrice = $state(100)
	let quantity = $state(1)
	let discountCode = $state('')
	let memberDiscount = $state(false)

	let subtotal = $derived(basePrice * quantity)
	let codeDiscount = $derived(discountCode === 'SAVE20' ? 0.2 : 0)
	let membershipDiscount = $derived(memberDiscount ? 0.1 : 0)
	let totalDiscount = $derived(codeDiscount + membershipDiscount)
	let finalPrice = $derived(subtotal * (1 - totalDiscount))
</script>

{@debug quantity, subtotal, totalDiscount, finalPrice}

<div class="configurator">
	<!-- inputs as before -->
</div>

Agora, sempre que qualquer um dos valores rastreados mudar, você verá a saída no console mostrando o estado atual. O registro é automático, reativo e não requer limpeza manual.

Uso Básico

Rastreamento de Valor Único

Rastreie um único valor reativo para entender quando ele muda:

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

{@debug count}

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

<p>Count: {count}</p>

Cada clique aciona a tag @debug, registrando o novo valor de count no console. A saída do console mostra:

{count: 1}
{count: 2}
{count: 3}

Esse padrão simples é perfeito para rastrear quando um valor específico é atualizado durante as interações do usuário.

Rastreamento de Múltiplos Valores

Rastreie múltiplos valores relacionados para entender como eles mudam juntos:

<script>
	let firstName = $state('')
	let lastName = $state('')
	let fullName = $derived(`${firstName} ${lastName}`.trim())
</script>

{@debug firstName, lastName, fullName}

<div class="form">
	<input bind:value={firstName} placeholder="First Name" />
	<input bind:value={lastName} placeholder="Last Name" />
	<p>Full Name: {fullName}</p>
</div>

A tag @debug dispara sempre que qualquer valor rastreado muda, exibindo todos os valores atuais:

{firstName: "A", lastName: "", fullName: "A"}
{firstName: "Al", lastName: "", fullName: "Al"}
{firstName: "Alice", lastName: "", fullName: "Alice"}
{firstName: "Alice", lastName: "C", fullName: "Alice C"}
{firstName: "Alice", lastName: "Ch", fullName: "Alice Ch"}
{firstName: "Alice", lastName: "Chen", fullName: "Alice Chen"}

Isso revela a cascata reativa: como a mudança de firstName ou lastName aciona a derivação de fullName.

Debug sem Parâmetros

Use @debug sem parâmetros para criar um breakpoint reativo:

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

	function addItem() {
		items = [...items, { id: Date.now(), value: Math.random() }]
	}
</script>

{#if items.length > 5}
	{@debug}
	<p class="warning">Many items detected!</p>
{/if}

<button onclick={addItem}>Add Item</button>
<p>{items.length} items</p>

Quando a condição se torna verdadeira, o @debug sem parâmetros aciona um breakpoint do depurador (se as ferramentas de desenvolvedor estiverem abertas), pausando a execução para inspeção. Isso é particularmente útil para capturar o estado em momentos críticos.

Padrões Avançados

Depurando Cadeias de Estado Derivado

Derivações complexas geralmente envolvem múltiplas etapas. Rastreie toda a cadeia para entender a propagação:

<script>
	let rawData = $state([
		{ value: 100, enabled: true },
		{ value: 200, enabled: false },
		{ value: 300, enabled: true }
	])

	let enabledItems = $derived(rawData.filter((item) => item.enabled))
	let values = $derived(enabledItems.map((item) => item.value))
	let sum = $derived(values.reduce((acc, val) => acc + val, 0))
	let average = $derived(enabledItems.length ? sum / enabledItems.length : 0)
</script>

{@debug enabledItems, values, sum, average}

<div class="data-panel">
	{#each rawData as item, i}
		<label>
			<input type="checkbox" bind:checked={item.enabled} />
			Value: {item.value}
		</label>
	{/each}

	<div class="results">
		<p>Sum: {sum}</p>
		<p>Average: {average.toFixed(2)}</p>
	</div>
</div>

Alternar checkboxes aciona a saída de depuração, mostrando como toda a cadeia de derivação é atualizada:

{
  enabledItems: [{value: 100, enabled: true}],
  values: [100],
  sum: 100,
  average: 100
}

{
  enabledItems: [{value: 100, enabled: true}, {value: 300, enabled: true}],
  values: [100, 300],
  sum: 400,
  average: 200
}

Isso deixa claro como habilitar um item se propaga em cascata por enabledItems → values → sum → average.

Depuração Condicional

Coloque tags @debug dentro de blocos condicionais para depurar cenários específicos:

<script>
	let user = $state(null)
	let permissions = $state([])

	let isAdmin = $derived(permissions.includes('admin'))
	let canEdit = $derived(permissions.includes('edit') || isAdmin)
</script>

{#if isAdmin}
	{@debug user, permissions, isAdmin, canEdit}
	<div class="admin-panel">
		<h2>Admin Controls</h2>
		<p>User: {user?.name}</p>
	</div>
{:else if canEdit}
	{@debug user, permissions, canEdit}
	<div class="editor-panel">
		<h2>Editor Controls</h2>
		<p>User: {user?.name}</p>
	</div>
{/if}

Tags @debug diferentes são ativadas com base no nível de permissão, registrando apenas quando o branch correspondente é renderizado. Essa abordagem direcionada reduz o ruído no console, exibindo apenas o estado relevante para cada cenário.

Depuração com Escopo de Loop

Depure o estado em cada iteração de um loop:

<script>
	let tasks = $state([
		{ id: 1, title: 'Review PR', completed: false, priority: 'high' },
		{ id: 2, title: 'Update docs', completed: true, priority: 'medium' },
		{ id: 3, title: 'Fix bug', completed: false, priority: 'critical' }
	])
</script>

{#each tasks as task (task.id)}
	{@const isUrgent = !task.completed && task.priority === 'critical'}

	{#if isUrgent}
		{@debug task, isUrgent}
	{/if}

	<div class="task" class:urgent={isUrgent}>
		<label>
			<input type="checkbox" bind:checked={task.completed} />
			{task.title}
		</label>
		<span class="priority">{task.priority}</span>
	</div>
{/each}

A saída de depuração dispara apenas para tarefas urgentes e é atualizada quando o status de conclusão da tarefa muda. Isso identifica problemas em iterações específicas do loop sem sobrecarregar o console com cada item.

Depurando Props e Bindings

Rastreie props recebidas e bindings bidirecionais para entender a comunicação entre componentes pai e filho:

<!-- Child.svelte -->
<script>
	let { value = $bindable(), min = 0, max = 100 } = $props()

	let clampedValue = $derived(Math.max(min, Math.min(max, value)))
	let isAtLimit = $derived(value !== clampedValue)
</script>

{@debug value, clampedValue, min, max, isAtLimit}

<div class="slider-widget">
	<input type="range" bind:value {min} {max} />
	<span class="value">{clampedValue}</span>
	{#if isAtLimit}
		<span class="warning">At limit!</span>
	{/if}
</div>

<!-- Parent.svelte -->
<script>
	import Child from './Child.svelte'

	let sliderValue = $state(50)
</script>

{@debug sliderValue}

<Child bind:value={sliderValue} min={0} max={100} />

Agora você pode ver o fluxo bidirecional: como as mudanças de estado do pai se propagam para o filho, e como as atualizações de entrada do filho fluem de volta para o pai. A saída de depuração de ambos os componentes revela o caminho completo de comunicação.

Exemplos do Mundo Real

Estado de Validação de Formulário

Rastreie estados de validação complexos em múltiplos campos:

<script>
	let email = $state('')
	let password = $state('')
	let confirmPassword = $state('')
	let agreeToTerms = $state(false)

	let emailValid = $derived(/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email))
	let passwordValid = $derived(password.length >= 8)
	let passwordsMatch = $derived(password === confirmPassword && password.length > 0)
	let formValid = $derived(emailValid && passwordValid && passwordsMatch && agreeToTerms)
</script>

{@debug emailValid, passwordValid, passwordsMatch, agreeToTerms, formValid}

<form>
	<label>
		Email:
		<input type="email" bind:value={email} />
		{#if email && !emailValid}
			<span class="error">Invalid email format</span>
		{/if}
	</label>

	<label>
		Password:
		<input type="password" bind:value={password} />
		{#if password && !passwordValid}
			<span class="error">Password must be at least 8 characters</span>
		{/if}
	</label>

	<label>
		Confirm Password:
		<input type="password" bind:value={confirmPassword} />
		{#if confirmPassword && !passwordsMatch}
			<span class="error">Passwords don't match</span>
		{/if}
	</label>

	<label>
		<input type="checkbox" bind:checked={agreeToTerms} />
		I agree to the terms and conditions
	</label>

	<button type="submit" disabled={!formValid}> Sign Up </button>
</form>

Conforme os usuários preenchem o formulário, a saída de depuração mostra exatamente quais condições de validação estão passando ou falhando em cada etapa, facilitando a identificação do motivo pelo qual o botão de envio permanece desabilitado.

Cálculos de Carrinho de Compras

Depure cálculos de preço em múltiplas etapas com descontos e impostos:

<script>
	let cartItems = $state([
		{ id: 1, name: 'Widget', price: 29.99, quantity: 2 },
		{ id: 2, name: 'Gadget', price: 49.99, quantity: 1 },
		{ id: 3, name: 'Gizmo', price: 19.99, quantity: 3 }
	])

	let couponCode = $state('')
	let shippingMethod = $state('standard')

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

	let couponDiscount = $derived.by(() => {
		if (couponCode === 'SAVE10') return subtotal * 0.1
		if (couponCode === 'SAVE20') return subtotal * 0.2
		return 0
	})

	let shippingCost = $derived.by(() => {
		if (shippingMethod === 'express') return 15.99
		if (shippingMethod === 'overnight') return 29.99
		return 5.99
	})

	let taxableAmount = $derived(subtotal - couponDiscount + shippingCost)
	let tax = $derived(taxableAmount * 0.08)
	let total = $derived(taxableAmount + tax)
</script>

{@debug subtotal, couponDiscount, shippingCost, taxableAmount, tax, total}

<div class="cart">
	<h2>Shopping Cart</h2>

	{#each cartItems as item (item.id)}
		<div class="cart-item">
			<span>{item.name}</span>
			<input type="number" bind:value={item.quantity} min="1" />
			<span>${(item.price * item.quantity).toFixed(2)}</span>
		</div>
	{/each}

	<div class="cart-controls">
		<label>
			Coupon Code:
			<input bind:value={couponCode} placeholder="Enter code" />
		</label>

		<label>
			Shipping:
			<select bind:value={shippingMethod}>
				<option value="standard">Standard ($5.99)</option>
				<option value="express">Express ($15.99)</option>
				<option value="overnight">Overnight ($29.99)</option>
			</select>
		</label>
	</div>

	<div class="cart-summary">
		<div class="line-item">
			<span>Subtotal:</span>
			<span>${subtotal.toFixed(2)}</span>
		</div>

		{#if couponDiscount > 0}
			<div class="line-item discount">
				<span>Coupon Discount:</span>
				<span>-${couponDiscount.toFixed(2)}</span>
			</div>
		{/if}

		<div class="line-item">
			<span>Shipping:</span>
			<span>${shippingCost.toFixed(2)}</span>
		</div>

		<div class="line-item">
			<span>Tax (8%):</span>
			<span>${tax.toFixed(2)}</span>
		</div>

		<div class="line-item total">
			<span>Total:</span>
			<span>${total.toFixed(2)}</span>
		</div>
	</div>
</div>

Cada interação — alterar quantidades, inserir um código de cupom, selecionar o frete — aciona a saída de depuração, revelando o fluxo completo de cálculo. Isso torna trivial verificar que os descontos são aplicados antes dos impostos, que o frete está incluído no valor tributável e que todas as fórmulas funcionam corretamente.

Pipeline de Filtro em Tempo Real

Depure operações complexas de filtragem e ordenação:

<script>
	let products = $state([
		{ id: 1, name: 'Laptop', category: 'electronics', price: 999, inStock: true, rating: 4.5 },
		{ id: 2, name: 'Desk', category: 'furniture', price: 299, inStock: true, rating: 4.2 },
		{ id: 3, name: 'Chair', category: 'furniture', price: 199, inStock: false, rating: 4.7 },
		{ id: 4, name: 'Mouse', category: 'electronics', price: 29, inStock: true, rating: 4.3 },
		{ id: 5, name: 'Monitor', category: 'electronics', price: 399, inStock: true, rating: 4.6 }
	]);

	let categoryFilter = $state('all');
	let minPrice = $state(0);
	let maxPrice = $state(1000);
	let showOutOfStock = $state(true);
	let sortBy = $state('name');

	let categoryFiltered = $derived(
		categoryFilter === 'all'
			? products
			: products.filter((p) => p.category === categoryFilter)
	);

	let priceFiltered = $derived(
		categoryFiltered.filter((p) => p.price >= minPrice && p.price <= maxPrice)
	);

	let stockFiltered = $derived(
		showOutOfStock
			? priceFiltered
			: priceFiltered.filter((p) => p.inStock)
	);

	let sorted = $derived.by(() => {
		const items = [...stockFiltered];
		if (sortBy === 'name') return items.sort((a, b) => a.name.localeCompare(b.name));
		if (sortBy === 'price') return items.sort((a, b) => a.price - b.price);
		if (sortBy === 'rating') return items.sort((a, b) => b.rating - a.rating);
		return items;
	});

	let categoryCount = $derived(categoryFiltered.length);
	let priceCount = $derived(priceFiltered.length);
	let stockCount = $derived(stockFiltered.length);
	let sortedCount = $derived(sorted.length);
</script>

{@debug categoryCount, priceCount, stockCount, sortedCount}

<div class="product-browser">
	<div class="filters">
		<label>
			Category:
			<select bind:value={categoryFilter}>
				<option value="all">All</option>
				<option value="electronics">Electronics</option>
				<option value="furniture">Furniture</option>
			</select>
		</label>

		<label>
			Price Range:
			<input type="number" bind:value={minPrice} min="0" />
			to
			<input type="number" bind:value={maxPrice} min="0" />
		</label>

		<label>
			<input type="checkbox" bind:checked={showOutOfStock} />
			Show out of stock
		</label>

		<label>
			Sort by:
			<select bind:value={sortBy}>
				<option value="name">Name</option>
				<option value="price">Price</option>
				<option value="rating">Rating</option>
			</select>
		</label>
	</div>

	<div class="product-grid">
		{#each sorted as product (product.id)}
			<div class="product-card" class:out-of-stock={!product.inStock}>
				<h3>{product.name}</h3>
				<p class="category">{product.category}</p>
				<p class="price">${product.price}</p>
				<p class="rating">★ {product.rating}</p>
				{#if !product.inStock}
					<p class="stock-status">Out of Stock</p>
				{/if}
			</div>
		{/each}
	</div>

	<p class="result-count">
		Showing {sorted.length} of {products.length} products
	</p>
</div>

A saída de depuração mostra quantos itens passam por cada estágio de filtragem:

{categoryCount: 5, priceCount: 5, stockCount: 5, sortedCount: 5}
{categoryCount: 3, priceCount: 3, stockCount: 3, sortedCount: 3}
{categoryCount: 3, priceCount: 2, stockCount: 2, sortedCount: 2}

Isso revela exatamente onde os itens são filtrados, facilitando a verificação da lógica de filtragem e o diagnóstico de por que certos produtos não aparecem.

Boas Práticas

Posicionamento Estratégico

Coloque tags @debug em pontos de decisão, não em todo lugar:

EVITE: Excesso de Logging:

<script>
	let a = $state(1)
	let b = $state(2)
	let c = $derived(a + b)
	let d = $derived(c * 2)
	let e = $derived(d - 1)
</script>

{@debug a}
{@debug b}
{@debug c}
{@debug d}
{@debug e}

PREFERIDO: Logging Estratégico:

<script>
	let a = $state(1)
	let b = $state(2)
	let c = $derived(a + b)
	let d = $derived(c * 2)
	let e = $derived(d - 1)
</script>

{@debug a, b, e}

Rastreie entradas e saídas finais, não etapas intermediárias, a menos que você precise especificamente depurar a cadeia de derivação.

Contexto Descritivo

Ao depurar cenários complexos, adicione comentários para identificar o que você está rastreando:

<!-- Debugging user authentication flow -->
{@debug user, isAuthenticated, sessionToken}

<!-- Debugging cart total calculation -->
{@debug subtotal, discount, shippingCost, total}

Isso ajuda ao revisitar o código mais tarde ou quando outros desenvolvedores precisam entender sua abordagem de depuração.

Temporário vs. Permanente

Depuração temporária — Investigação rápida:

{@debug someValue}

Remova após resolver o problema.

Depuração permanente — Somente em modo de desenvolvimento:

{#if import.meta.env.DEV}
	{@debug criticalState, userActions, systemHealth}
{/if}

Mantenha as tags de depuração nos builds de desenvolvimento, mas exclua-as da produção.

Combine com Renderização Condicional

Depure apenas quando ocorrerem problemas:

<script>
	let apiResponse = $state(null)
	let isError = $derived(apiResponse?.status === 'error')
</script>

{#if isError}
	{@debug apiResponse}
	<div class="error-panel">
		<h3>Something went wrong</h3>
		<p>{apiResponse.message}</p>
	</div>
{/if}

Isso garante que a saída de depuração só seja acionada quando a condição de erro for verdadeira, mantendo seu console limpo durante a operação normal.

Armadilhas Comuns

Excesso de Logging

Rastrear muitos valores gera ruído:

EVITE: Rastreamento Excessivo

{@debug var1, var2, var3, var4, var5, var6, var7, var8, var9, var10}

PREFERIDO: Rastreamento Focado

{@debug suspectedProblemValue, relatedDependency}

Concentre-se nos valores específicos envolvidos no problema que você está investigando.

Esquecer de Remover

Deixar tags @debug no código de produção:

EVITE: Deixado em Produção

<script>
	let userData = $state(null)
</script>

{@debug userData}

PREFERIDO: Consciente do Ambiente

<script>
	let userData = $state(null)
</script>

{#if import.meta.env.DEV}
	{@debug userData}
{/if}

Ou remova completamente antes de fazer commit em branches de produção.

Incompreensão do Escopo Reativo

@debug só é acionado quando valores rastreados mudam. Se você não está vendo a saída, os valores podem não ser reativos:

EVITE: Valor Não Reativo

<script>
	let config = { theme: 'dark', layout: 'grid' }
</script>

{@debug config}

config é uma variável comum. Alterações em suas propriedades não acionarão a tag de debug.

PREFIRA: Valor Reativo

<script>
	let config = $state({ theme: 'dark', layout: 'grid' })
</script>

{@debug config}

Agora config é reativo, e mutações acionarão a saída de debug.

Depurando Estado Assíncrono

@debug mostra os valores atuais, mas não ajuda com o timing assíncrono:

Visibilidade Limitada:

<script>
	let data = $state(null)
	let loading = $state(false)

	async function fetchData() {
		loading = true
		data = await fetch('/api/data').then((r) => r.json())
		loading = false
	}
</script>

{@debug data, loading}

Você verá as mudanças de estado, mas não o timing da resolução da promise. Para depuração assíncrona, combine @debug com console.log na função assíncrona:

<script>
	let data = $state(null)
	let loading = $state(false)

	async function fetchData() {
		loading = true
		console.log('Fetch started')
		data = await fetch('/api/data').then((r) => r.json())
		console.log('Fetch completed', data)
		loading = false
	}
</script>

{@debug data, loading}

Isso fornece tanto o rastreamento de estado reativo quanto insights sobre o timing assíncrono.

Integração com Ferramentas de Desenvolvedor

Formato de Saída no Console

Quando @debug é acionado, ele registra no console com os nomes das variáveis rastreadas como chaves:

{@debug firstName, lastName, age}

Saída no console:

{firstName: "Alice", lastName: "Chen", age: 29}

Essa saída estruturada se integra perfeitamente às ferramentas de desenvolvedor do navegador, permitindo que você expanda objetos, arrays e estruturas aninhadas.

Comportamento de Breakpoint

@debug sem parâmetros funciona como um breakpoint condicional:

{#if errorCondition}
	{@debug}
{/if}

Quando a condição é verdadeira e as ferramentas de desenvolvedor estão abertas, a execução é pausada, permitindo que você inspecione a pilha de chamadas e o estado das variáveis. Se as ferramentas de desenvolvedor estiverem fechadas, a tag @debug não tem efeito.

Considerações de Desempenho

Tags @debug têm impacto mínimo no desempenho durante o desenvolvimento, mas não devem ser implantadas em produção. Use verificações de ambiente em tempo de build para excluí-las:

{#if import.meta.env.DEV}
	{@debug importantState}
{/if}

A maioria dos bundlers (Vite, Webpack, Rollup) eliminará completamente esse bloco em builds de produção por meio da eliminação de código morto.

Comparação com a Depuração Tradicional

`@debug` vs. `console.log`

Abordagem com console.log:

<script>
	let count = $state(0)

	$effect(() => {
		console.log('Count changed:', count)
	})
</script>

Requer configuração e limpeza manuais do $effect. O effect é executado em cada mudança de dependência reativa, não apenas em count.

Abordagem com @debug:

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

{@debug count}

Automático, declarativo e acionado apenas quando count muda. Sem necessidade de effects manuais ou limpeza.

`@debug` vs. Breakpoints

Breakpoints tradicionais:

Definidos nas ferramentas de desenvolvedor
Locais estáticos no código
Interrompem em cada execução dessa linha

Breakpoints com @debug:

Declarados no template
Reativos — acionados apenas quando as condições mudam
Podem ser condicionais com base na lógica do template

Ambas as abordagens têm valor. Use @debug para rastreamento de estado reativo, e breakpoints tradicionais para fluxo de código imperativo.

Estratégias Avançadas de Depuração

Depurando Máquinas de Estado

Rastreie transições de estado em máquinas de estado finito:

<script>
	let state = $state('idle')
	let error = $state(null)
	let data = $state(null)

	async function load() {
		state = 'loading'
		error = null
		try {
			data = await fetch('/api/data').then((r) => r.json())
			state = 'success'
		} catch (e) {
			error = e.message
			state = 'error'
		}
	}
</script>

{@debug state, error, data}

<div class="state-machine">
	{#if state === 'idle'}
		<button onclick={load}>Load Data</button>
	{:else if state === 'loading'}
		<p>Loading...</p>
	{:else if state === 'success'}
		<div class="data">{JSON.stringify(data)}</div>
	{:else if state === 'error'}
		<div class="error">{error}</div>
	{/if}
</div>

A saída de debug mostra cada transição de estado, revelando o fluxo completo pela máquina de estado.

Depurando Cadeias de Estado Derivado

Rastreie valores derivados ao longo de uma cadeia reativa:

<script>
	let count = $state(0)
	let doubled = $derived(count * 2)
	let tripled = $derived(count * 3)
</script>

{@debug count, doubled, tripled}

<button onclick={() => count++}>Increment</button>
<p>Count: {count}, Doubled: {doubled}, Tripled: {tripled}</p>

Ao rastrear valores de store com o prefixo $, você vê como as mudanças de store se propagam por meio dos valores derivados.

Depurando o Ciclo de Vida de Componentes

Acompanhe quando os componentes são montados, atualizados e destruídos:

<script>
	let { data } = $props()
	let mounted = $state(false)
	let updateCount = $state(0)

	$effect(() => {
		mounted = true
		return () => {
			console.log('Component unmounting, updates:', updateCount)
		}
	})

	$effect(() => {
		data // Track data changes
		updateCount++
	})
</script>

{@debug mounted, updateCount, data}

<div class="component">
	<p>Mounted: {mounted}</p>
	<p>Update Count: {updateCount}</p>
	<p>Data: {JSON.stringify(data)}</p>
</div>

Essa combinação de @debug, $effect e console.log fornece visibilidade abrangente do ciclo de vida.

Conclusão

A tag @debug transforma a depuração de um processo tedioso e manual em uma experiência declarativa e reativa que se alinha perfeitamente ao modelo reativo do Svelte. Ao posicionar tags de depuração em pontos estratégicos dos seus templates, você obtém visibilidade em tempo real sobre mudanças de estado, fluxo de dados e comportamento de componentes sem poluir a seção de script com código de log.

A chave para um uso eficaz do @debug está no posicionamento estratégico: rastreie entradas e saídas, não cada valor intermediário. Concentre-se em pontos de decisão, computações derivadas e cadeias reativas onde entender o estado atual é fundamental. Combine @debug com renderização condicional para ativar o log apenas quando problemas ocorrerem, mantendo o console limpo durante a operação normal.

Lembre-se de que @debug é uma ferramenta de desenvolvimento. Envolva as tags de depuração em verificações de ambiente ou remova-as antes de implantar em produção. Quando usado com discernimento, o @debug se torna uma ferramenta de diagnóstico inestimável que acelera o desenvolvimento, simplifica a depuração e aprofunda sua compreensão do gerenciamento de estado reativo no Svelte 5.

Domine o @debug e você passará menos tempo adivinhando sobre mudanças de estado e mais tempo desenvolvendo funcionalidades com confiança.

Principais Conclusões

{@debug} fornece depuração declarativa e reativa que registra automaticamente valores sempre que as dependências mudam, acionando um breakpoint de debugger quando o DevTools está aberto
Múltiplas variáveis podem ser rastreadas em uma única tag usando a sintaxe {@debug var1, var2, var3}, registrando todos os valores juntos quando qualquer dependência muda
O posicionamento estratégico amplifica a eficácia - posicione as tags de depuração em limites condicionais, pontos de computação derivada e antes/depois de mutações de estado para rastrear o fluxo de dados
Depuração condicional com blocos {#if} permite log direcionado apenas quando condições específicas ocorrem (ex.: {#if error}{@debug error, context}{/if})
A saída de log formatada inclui localização do código-fonte, nome do componente e exibição estruturada de valores com realce de sintaxe nos consoles do navegador
A segurança em produção requer verificações de ambiente - envolva as tags de depuração com {#if import.meta.env.DEV} ou remova-as completamente antes da implantação
Complementar ao $effect para depuração de efeitos colaterais - use @debug para log reativo e $effect para inspeção programática com console.trace() ou lógica personalizada
A integração com TypeScript fornece segurança de tipos com inferência adequada para variáveis depuradas e erros em tempo de compilação para referências indefinidas

Veja Também

Documentação Oficial do Svelte 5 - {@debug}
MDN Web Docs - instrução debugger
Chrome DevTools - Depuração de JavaScript
$effect - Efeitos colaterais reativos para depuração programática
$inspect - A rune de depuração aprimorada do Svelte 5 com log formatado
Console API - Métodos de log do navegador para depuração
Variáveis de Ambiente do Vite - Gerenciando os modos de desenvolvimento e produção

Depuração Reativa no Nível do Template

O Problema

O Desafio da Depuração

A Solução com @debug

Uso Básico

Rastreamento de Valor Único

Rastreamento de Múltiplos Valores

Debug sem Parâmetros

Padrões Avançados

Depurando Cadeias de Estado Derivado

Depuração Condicional

Depuração com Escopo de Loop

Depurando Props e Bindings

Exemplos do Mundo Real

Estado de Validação de Formulário

Cálculos de Carrinho de Compras

Pipeline de Filtro em Tempo Real

Boas Práticas

Posicionamento Estratégico

Contexto Descritivo

Temporário vs. Permanente

Combine com Renderização Condicional

Armadilhas Comuns

Excesso de Logging

Esquecer de Remover

Incompreensão do Escopo Reativo

Depurando Estado Assíncrono

Integração com Ferramentas de Desenvolvedor

Formato de Saída no Console

Comportamento de Breakpoint

Considerações de Desempenho

Comparação com a Depuração Tradicional

@debug vs. console.log

@debug vs. Breakpoints

Estratégias Avançadas de Depuração

Depurando Máquinas de Estado

Depurando Cadeias de Estado Derivado

Depurando o Ciclo de Vida de Componentes

Conclusão

Principais Conclusões

Veja Também

A Solução com `@debug`

`@debug` vs. `console.log`

`@debug` vs. Breakpoints