Estado Reativo que Simplesmente Funciona

A rune $state é a base do sistema de reatividade do Svelte 5. Ela transforma variáveis JavaScript comuns em estado reativo que aciona automaticamente atualizações na interface quando alterado. Ao contrário de outros frameworks que exigem objetos wrapper ou funções setter, o Svelte permite que você trabalhe com valores reativos como se fossem variáveis normais — o compilador cuida da mágica nos bastidores.

Este tutorial vai desde o uso básico até padrões avançados, cobrindo reatividade profunda, mecânica de proxy, otimização de desempenho com $state.raw, e as armadilhas comuns que pegam até desenvolvedores experientes de surpresa.

O que é `$state`?

$state é uma rune que torna uma variável reativa. Quando uma variável reativa muda, o Svelte atualiza automaticamente qualquer parte da sua interface que a utiliza.

Uso Básico

Aqui está o exemplo mais simples possível:

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

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

Vamos analisar isso passo a passo:

let count = $state(0) - Cria uma variável reativa chamada count com valor inicial 0
onclick={() => count++} - Ao clicar, incrementa count em 1
{count} - Exibe o valor atual de count no texto do botão

O que acontece quando você clica:

O manipulador de clique executa count++
O Svelte detecta que count mudou
O Svelte atualiza automaticamente o texto do botão para mostrar o novo valor

Você nunca precisa atualizar o DOM manualmente. Esse é o poder da reatividade!

Por que `$state` é Diferente de Outros Frameworks

Se você já usou React, Vue ou outros frameworks, pode estar acostumado com uma sintaxe assim:

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

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

O Svelte é diferente. Com $state, você interage com a variável diretamente:

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

Sem objetos wrapper, sem funções setter, sem .value. É apenas um número, e você o usa como um número. Essa é a filosofia do Svelte: manter as coisas simples e próximas do JavaScript puro.

Como Funciona por Baixo dos Panos (Simplificado)

Quando você escreve let count = $state(0), o compilador do Svelte transforma seu código. Aqui está uma versão simplificada do que acontece:

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

O compilador envolve cada leitura e escrita da variável com funções especiais que:

Rastreiam quais partes da interface dependem desta variável
Notificam essas partes quando a variável muda

Por que isso importa? Isso explica por que as runes só funcionam em arquivos .svelte e arquivos .svelte.js/.svelte.ts — esses são os únicos arquivos que o compilador do Svelte processa.

Onde Você Pode Usar `$state`?

Você pode usar $state em:

Local	Exemplo
Blocos `<script>` de componentes	`let name = $state('Alice')`
Arquivos `.svelte.js` / `.svelte.ts`	Para estado reativo compartilhado
Campos de classe	`class Counter { count = $state(0) }`

Você não pode usar $state em:

Arquivos .js ou .ts comuns (o compilador não os processa)
Fora do bloco <script> em um arquivo .svelte

Perguntas Comuns de Iniciantes

P: E se eu não usar $state?

Sem $state, as mudanças não atualizam a interface:

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

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

A variável muda internamente, mas o Svelte não sabe disso, então a interface nunca é atualizada.

P: Posso usar $state com qualquer tipo de valor?

Sim! $state funciona com qualquer 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>

Reatividade Profunda: A Mágica dos Proxies

O que é Reatividade Profunda?

Quando você passa um objeto ou array para $state, algo especial acontece: o Svelte o torna profundamente reativo. Isso significa que mudanças em propriedades aninhadas (não importa quão profundas) acionam automaticamente atualizações na interface.

Entendendo o Conceito: Uma Analogia Simples

Pense na reatividade profunda como um sistema de segurança em um edifício.

Com monitoramento superficial (variáveis comuns), você observa apenas a porta da frente. Se alguém entrar por uma janela ou pela porta dos fundos, você não percebe.

Com monitoramento profundo (objetos/arrays com $state), você tem câmeras em cada sala, cada corredor, cada armário. Qualquer mudança em qualquer lugar do edifício aciona um alerta.

Como Funciona a Reatividade Profunda

Quando você cria um objeto reativo:

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

O Svelte envolve o objeto em um Proxy. Um Proxy é um recurso do JavaScript que intercepta operações em um objeto — como leitura ou escrita de propriedades.

Veja o que acontece quando você altera uma propriedade aninhada:

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

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

Passo a passo:

Você escreve em user.address.city
O Proxy intercepta essa operação de escrita
O Svelte registra que user.address.city mudou
O Svelte encontra todos os elementos da interface que usam user.address.city
O Svelte atualiza apenas esses elementos (não a página inteira!)

Reatividade Profunda com Arrays

Arrays recebem o mesmo tratamento de reatividade profunda, incluindo seus 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>

O que é incrível aqui:

Métodos de array funcionam: todos.push() aciona uma atualização. O mesmo vale para pop(), splice(), shift(), etc.
Objetos aninhados são reativos: Alterar todo.done atualiza apenas aquele checkbox
Novos itens tornam-se reativos: Quando você faz push de um novo objeto, ele automaticamente se torna reativo
Atualizações granulares: Marcar um checkbox não re-renderiza a lista inteira — apenas aquele item específico

Representação Visual da Reatividade 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 nível de aninhamento recebe seu próprio wrapper de Proxy, tornando todas as propriedades reativas.

A reatividade profunda permite atualizações granulares. Quando você altera user.address.city, apenas os elementos da interface que dependem dessa propriedade específica são re-renderizados — não o componente inteiro.

O Que É Proxificado (E O Que Não É)

Svelte envolve coisas em Proxies recursivamente até encontrar algo que não seja um objeto simples ou array.

Estes SÃO tornados profundamente reativos:

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

Estes NÃO são tornados profundamente reativos:

<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 que a distinção?

Objetos simples e arrays são as estruturas de dados mais comuns, e o Svelte pode envolvê-los com segurança. Mas instâncias de classes têm comportamento personalizado (métodos, getters, etc.) que os Proxies podem interferir. Objetos nativos como Map e Set têm slots internos que os Proxies não conseguem acessar.

Classes Nativas Reativas do Svelte

Svelte fornece SvelteMap, SvelteSet, SvelteDate e SvelteURL em svelte/reactivity. Use esses substitutos diretos sempre que precisar de coleções ou datas reativas — eles funcionam exatamente como seus equivalentes nativos.

Para Map, Set, Date e URL, o Svelte fornece versões reativas que você pode 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>

Eles funcionam como seus equivalentes nativos, mas são totalmente reativos.

Quando a Reatividade Quebra

Entender quando a reatividade não funciona é tão importante quanto saber quando ela funciona. Esses são os erros mais comuns que os desenvolvedores cometem.

1: Desestruturação Quebra a Reatividade

Desestruturar um objeto $state fornece valores JavaScript simples — não referências reativas. Alterações no objeto original não atualizarão as variáveis desestruturadas.

O que acontece: Quando você desestrutura um objeto reativo, você extrai os valores atuais naquele momento — não referências reativas.

Analogia: Imagine tirar uma foto de um relógio. A foto mostra a hora em que você a tirou, mas ela não se atualiza conforme o tempo passa. Desestruturar é como tirar uma foto dos seus dados.

<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 que acontece:

let { done, text } = todo

Isso é equivalente a:

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

done agora é apenas uma variável comum que contém false. Ela não tem mais nenhuma conexão com todo.

A Correção: Sempre acesse propriedades através do objeto reativo.

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

Quando a desestruturação É aceitável:

A desestruturação é válida quando você precisa de um snapshot pontual:

<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: Reatribuição vs. Mutação

Qual é a diferença?

Mutação: Alterar algo dentro de um objeto/array
Reatribuição: Substituir o objeto/array inteiro por um novo

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

Ambas as abordagens funcionam com $state. A diferença importa para:

Desempenho (veja a seção posterior)
$state.raw (apenas reatribuição funciona)
Preferências de estilo de código

Entendendo o 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: Passando State para Funções (O Problema de Passagem por Valor)

O que acontece: O JavaScript passa valores, não referências. Quando você passa um valor de $state para uma função, você está passando o valor atual naquele momento.

Analogia: É como dizer um número de telefone verbalmente para alguém. Se você mudar seu número depois, a pessoa ainda tem o antigo 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 que acontece:

Quando addNumbers(x, y) é chamado:

x é avaliado como 1
y é avaliado como 2
A função recebe os valores 1 e 2
Ela retorna 3
total é definido como 3

Alterações posteriores em x e y não re-executam addNumbers.

A Correção: Use $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! -->

Correção Alternativa: Passe um Objeto

Se você precisar passar state para uma função, passe um objeto em vez 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: Instâncias de Classes Não São Proxificadas

O que acontece: Quando você envolve uma instância de classe em $state, a instância em si não se torna reativa. Apenas objetos simples e arrays recebem o tratamento 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 que acontece: Classes geralmente têm métodos, getters, setters e lógica interna que os Proxies podem interferir. O Svelte age com cautela ao não proxificar instâncias de classes.

A Correção: Use $state dentro dos campos da classe

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

Percepção chave: Coloque $state nos campos reativos, não na instância da classe.

5: Exportando State Entre Módulos

Exportar um primitivo $state e reatribuí-lo dentro de outro módulo não propagará a atualização. Exporte um objeto e mute suas propriedades — ou use funções getter.

O que acontece: Você não pode exportar diretamente uma variável $state que é reatribuída.

// 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 que acontece: O compilador do Svelte transforma cada arquivo de forma independente. Quando outro arquivo importa count, ele obtém uma referência que o compilador daquele arquivo não sabe como lidar.

A Correção: Opção 1 - Exporte um 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>

A Correção: Opção 2 - Use Funções 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: O Problema de Binding do `this` em Classes

O que acontece: Quando você passa um método de classe como um handler de evento, o this pode não ser o que você espera.

<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 que acontece: Em JavaScript, this é determinado por como uma função é chamada, não por onde ela é definida. Quando o Svelte chama counter.increment como um handler de evento, o this se torna o elemento button.

As Correções:

<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 com `$state.raw`

O que é `$state.raw`?

$state.raw cria estado reativo que NÃO é profundamente proxificado. Alterações em propriedades dentro do objeto/array não dispararão atualizações — apenas a reatribuição da variável inteira irá fazê-lo.

Quando Você Usaria Isso?

Analogia: Imagine que você é um bibliotecário com duas abordagens para rastrear livros:

Rastreamento profundo ($state): Você tem um sensor em tempo real em cada livro individual. Você sabe no instante em que qualquer livro é movido, aberto ou tocado.
Rastreamento superficial ($state.raw): Você só rastreia quando prateleiras inteiras são substituídas. Você não sabe se livros individuais foram movidos.

O rastreamento profundo é preciso, mas requer mais sensores (memória/CPU). O rastreamento superficial é mais simples e rápido quando você só se preocupa com mudanças totais.

Como 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 que Usar `$state.raw`?

Às vezes você não precisa de reatividade profunda. Se você sempre está substituindo o objeto/array inteiro e nunca o mutando, $state.raw pode ser mais eficiente. Ele evita a sobrecarga de criar Proxies para cada propriedade aninhada. Vamos dar uma olhada em alguns cenários específicos onde $state.raw pode ser benéfico:

1: Desempenho com Grandes Volumes de Dados

A proxificação profunda tem sobrecarga. Para arrays grandes (milhares de itens) que você substitui inteiramente, $state.raw é mais 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: Padrões de Dados Imutáveis

Se você está seguindo princípios de dados imutáveis (sempre criando novos objetos em vez de mutá-los), $state.raw combina com esse 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: Integração com Bibliotecas Externas

Algumas bibliotecas esperam objetos simples, não Proxies. $state.raw fornece dados não proxificados.

`$state.raw` Pode Conter Estado Reativo

Aqui está um padrão poderoso: um array bruto onde cada item é individualmente reativo.

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

Isso oferece o melhor dos dois mundos:

Atualizações eficientes de array (apenas reatribuição)
Reatividade granular por item (cada tarefa é atualizada de forma independente)

Use $state.raw para arrays grandes (mais de 1000 itens) que você substitui inteiramente. É de 3 a 5 vezes mais rápido porque ignora o envolvimento por proxy profundo.

`$state.snapshot`: Obtendo Objetos Simples

Quando você precisa passar um objeto reativo para código que não espera Proxies (como JSON.stringify ou bibliotecas externas), use $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>

Considerações de Desempenho

Quando a Reatividade Profunda Ajuda o Desempenho

A reatividade profunda permite atualizações granulares. Quando você altera uma propriedade específica, apenas os elementos de UI que dependem dessa propriedade são re-renderizados.

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

Sem reatividade profunda (ou com um framework que não a possui), alterar uma caixa de seleção pode re-renderizar a lista inteira!

Quando a Reatividade Profunda Prejudica o Desempenho

A proxificação profunda tem sobrecarga. Para conjuntos de dados muito grandes que você substitui inteiramente (nunca muta), essa sobrecarga é desperdiçada.

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

Quando Usar `$state` vs `$state.raw`

Use `$state` quando...	Use `$state.raw` quando...
Você muta propriedades individuais	Você sempre substitui o valor inteiro
Os dados são interativos para o usuário	Os dados vêm de uma API
Dados de tamanho pequeno a médio	Grandes conjuntos de dados (1000+ itens)
Você precisa de atualizações granulares	Você só precisa de atualizações totais

Exemplos Práticos

1: Carrinho de Compras

Um carrinho de compras completo demonstrando $state, $derived e reatividade baseada em classes.

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

Principais conclusões deste exemplo:

A mutação funciona: cartItems.push(), item.quantity++ e splice() disparam atualizações
Cadeias derivadas: cartWithDetails depende de cartItems e products; cartTotal depende de cartWithDetails
Atualizações granulares: Alterar a quantidade de um item recalcula apenas o necessário

2: Classe de Temporizador Reativo

Este exemplo mostra como usar corretamente $state e $derived dentro de uma classe.

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

Referência Rápida

Criando Estado

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

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

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

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

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

Usando Estado em Classes

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

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

Estado Compartilhado Entre Módulos

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

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

Principais Conclusões

A rune $state é enganosamente simples na superfície, mas poderosa por baixo:

$state() torna valores reativos — Use para qualquer dado que deva acionar atualizações de UI quando modificado.
Reatividade profunda é automática — Objetos e arrays se tornam proxies profundamente reativos. Mutações em qualquer nível acionam atualizações.
Saiba quando a reatividade quebra — Desestruturação, passagem de primitivos para funções e instâncias de classes são armadilhas comuns. Acesse propriedades através de objetos reativos.
$state.raw() para desempenho — Use para grandes conjuntos de dados que você substitui em vez de mutar.
Classes precisam de $state() nos campos — Coloque $state() nos campos que devem ser reativos, não na instância da classe.
Use $state.snapshot() — Quando precisar de objetos simples para código externo ou depuração.

Com esses padrões dominados, você terá uma base sólida para construir aplicações reativas com Svelte 5.