O Contador Congelado

Você aprendeu a mecânica do contexto: como setContext transmite dados e getContext os recebe. Você viu como o contexto flui pela árvore de componentes e como o ancestral mais próximo prevalece. Tudo faz sentido até você tentar construir algo real.

Você cria um contador no seu provedor, compartilha-o via contexto e conecta um botão para incrementá-lo. O botão funciona — você consegue ver o valor aumentando no provedor. Mas o componente consumidor? Está congelado. Ainda mostra o valor original. Clique após clique, nada muda. O que está acontecendo?

Este é o momento em que os desenvolvedores percebem que o contexto em si não rastreia mudanças. É um mecanismo de entrega único, não um fluxo de dados ao vivo. O valor que os consumidores recebem é um instantâneo do momento em que chamaram getContext, e mudanças na fonte não se propagam automaticamente.

Mas aqui está a boa notícia: as runes do Svelte 5 resolvem isso de forma elegante. Ao entender por que o contexto simples não é reativo e como $state corrige isso, você construirá um contexto que se atualiza em todos os lugares, automaticamente.

Este guia desenvolve sua compreensão progressivamente em quatro etapas:

O Problema do Instantâneo — Por que o contexto captura valores congelados e o que isso significa para seus dados
A Base — Usando objetos $state para criar referências compartilhadas e reativas
A Regra de Ouro — Por que a mutação funciona e a reatribuição quebra tudo
Padrões Avançados — Getters para valores computados e encapsulamento

Ao final, você terá um modelo mental completo para contexto reativo que escala de contadores simples a estados de aplicação complexos.

O Espaço do Problema: Por Que o Contexto Captura Instantâneos

Antes de resolver o problema, vamos entendê-lo profundamente. Isso não é acadêmico — saber por que os valores de contexto não se atualizam vai ajudá-lo a depurar problemas, projetar APIs melhores e evitar os frustrantes momentos de "por que isso não está funcionando?" que afligem desenvolvedores novos no contexto do Svelte.

O Problema do Contador Congelado

Vamos começar com um código que parece perfeitamente razoável, mas não funciona:

<!-- Provider.svelte -->
<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let count = 0

	setContext('count', count) // Captures 0

	function increment() {
		count++ // count becomes 1, 2, 3...
		// But context still holds 0!
	}
</script>

<button onclick={increment}>
	Provider sees: {count}
</button>

{@render children()}

<!-- Consumer.svelte -->
<script>
	import { getContext } from 'svelte'

	const count = getContext('count') // Gets 0, forever
</script>

<p>Consumer sees: {count}</p> <!-- Always 0, never updates! -->

O botão do provedor mostra 1, 2, 3... mas o consumidor fica preso em 0 para sempre. Clique o botão cem vezes — nada muda no consumidor.

O Que Realmente Acontece Por Baixo dos Panos

Quando setContext('count', count) é executado durante a inicialização do componente, o JavaScript avalia count naquele exato momento e passa o resultado para o Svelte. É isso. Nenhum link mágico é criado, nenhuma assinatura é estabelecida, nenhuma conexão contínua é mantida.

Vamos percorrer a execução passo a passo:

// Inside Provider.svelte's <script>

let count = 0

setContext('count', count)
// What happens internally:
// 1. JavaScript evaluates the expression 'count'
// 2. Since count is 0, the expression evaluates to the NUMBER 0
// 3. Svelte receives: setContext('count', 0)
// 4. Svelte stores in its context map: { 'count': 0 }
// 5. Done. The variable 'count' and the stored value are now independent.

function increment() {
	count++
	// The variable 'count' changes: 0 → 1 → 2 → 3...
	// But the context store still has: { 'count': 0 }
	// There's no link between them!
}

O Modelo Mental da Fotografia

Pense em setContext como tirar uma fotografia. No momento em que você tira a foto, você captura exatamente como a cena está. Se a cena mudar depois — alguém se move, a iluminação muda, os anos passam — sua fotografia não se atualiza. Está congelada no tempo.

Time 0 (component initialization):
┌─────────────────┐       snapshot    ┌─────────────────┐
│ Provider        │   ─────────────>  │ Context Store   │
│ count = 0       │                   │ 'count' → 0     │
└─────────────────┘                   └─────────────────┘

Time 1, 2, 3... (after increments):
┌─────────────────┐                   ┌─────────────────┐
│ Provider        │    (no link)      │ Context Store   │
│ count = 1, 2, 3 │                   │ 'count' → 0     │  ← Still 0!
└─────────────────┘                   └─────────────────┘

O armazenamento de contexto guarda uma "fotografia" do valor no tempo 0. Quando a variável original muda, a fotografia permanece a mesma.

Por Que o JavaScript Funciona Assim

Esse comportamento não é uma limitação do Svelte — é fundamental para como o JavaScript lida com valores primitivos. Quando você passa um primitivo (número, string, booleano) para uma função, o JavaScript copia o valor:

let count = 0
const stored = count // stored gets the VALUE 0, not a reference to count

count = 100
console.log(count) // 100
console.log(stored) // Still 0!

Para primitivos, o JavaScript sempre copia o valor. Não há como criar uma "referência viva" para um primitivo — simplesmente não é assim que a linguagem funciona.

Objetos São Diferentes (Mas Ainda Complicados)

Objetos são passados por referência, o que significa que algo diferente acontece:

<!-- Provider.svelte -->
<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	const user = { name: 'Alice', score: 0 }

	setContext('user', user)
	// Context stores a REFERENCE to the same object in memory

	function addPoint() {
		user.score++ // Modifying the shared object
	}
</script>

<button onclick={addPoint}>Add Point</button>
{@render children()}

<!-- Consumer.svelte -->
<script>
	import { getContext } from 'svelte'

	const user = getContext('user')
	// Gets a reference to the SAME object as the provider
</script>

<p>Score: {user.score}</p>

Quando o provedor chama addPoint(), o user.score do consumidor também muda — eles estão apontando para o mesmo objeto na memória. Mas ainda há um problema: o Svelte não sabe que a mutação aconteceu. O componente consumidor não será re-renderizado para mostrar a nova pontuação.

É aqui que entra o $state.

O Modelo Mental do Svelte 5: Referências Reativas

A percepção fundamental para o contexto reativo é esta: precisamos de duas coisas funcionando juntas.

Uma referência compartilhada para que tanto o provedor quanto o consumidor acessem os mesmos dados
A consciência do Svelte para que o Svelte saiba quando os dados mudam e possa atualizar a UI

Usar $state com um objeto nos fornece ambas.

O Padrão Fundamental

<!-- Provider.svelte -->
<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	// Step 1: Create reactive state as an OBJECT
	let counter = $state({ value: 0 })

	// Step 2: Share the reactive object via context
	setContext('counter', counter)

	function increment() {
		counter.value++ // Svelte tracks this mutation
	}
</script>

<button onclick={increment}>
	Provider: {counter.value}
</button>

{@render children()}

<!-- Consumer.svelte -->
<script>
	import { getContext } from 'svelte'

	// Step 3: Get the same reactive object
	const counter = getContext('counter')
</script>

<p>Consumer: {counter.value}</p>
<!-- Now this updates automatically! -->

Clique no botão e observe os dois números aumentarem juntos. O consumidor não está mais congelado.

Por Que Isso Funciona: Rastreando o Fluxo de Dados

Vamos rastrear o que acontece com esse padrão:

Time 0 (initialization):
┌──────────────────┐              ┌─────────────────┐
│ Provider         │   reference  │ Context Store   │
│ counter          ┼─────────────>│ 'counter' ───┐  │
└──────────────────┘              └──────────────┼──┘
                                                 │
                    ┌────────────────────────────┘
                    │
                    ▼
            { value: 0 }  ← Reactive $state object in memory
                    ▲
                    │
┌──────────────────┐│
│ Consumer         ││
│ counter ─────────┘│
└───────────────────┘

Both Provider and Consumer point to the SAME object in memory.

Quando o provedor muta counter.value:

O sistema de reatividade do Svelte detecta a mudança (porque o objeto foi criado com $state)
O Svelte marca qualquer componente que leia counter.value como precisando de re-renderização
O consumidor é re-renderizado com o novo valor

O ingrediente mágico é o $state. Sem ele, você teria um objeto compartilhado, mas o Svelte não saberia quando ele mudou.

Objetos são passados por referência em JavaScript. Quando você faz setContext('counter', counter), o contexto armazena uma referência ao objeto — não uma cópia. O provedor, o contexto e todos os consumidores apontam para o mesmo objeto na memória. Mute-o em qualquer lugar e todos verão a mudança.

Por Que Primitivos Não Funcionam Diretamente

Um primitivo simples como let count = $state(0) não funcionará para o contexto porque você não pode compartilhar uma referência a ele:

<!-- AVOID: This doesn't work as expected -->
<script>
	import { setContext } from 'svelte'

	let count = $state(0)

	setContext('count', count)
	// This stores the VALUE 0, not a reference to the $state
	// It's the same snapshot problem all over again!
</script>

Sempre envolva em um objeto:

<!-- ✅ This works -->
<script>
	import { setContext } from 'svelte'

	let counter = $state({ value: 0 })

	setContext('counter', counter)
	// This stores a REFERENCE to the $state object
</script>

Isso pode parecer verboso no início, mas é explícito e previsível. Você sempre sabe que os valores de contexto são objetos que você pode mutar.

A Regra de Ouro: Mute, Não Reatribua

Agora para a regra mais importante no contexto reativo — a que confunde desenvolvedores mais do que qualquer outra. Entender isso profundamente vai economizar horas de depuração.

Quando você tem um objeto de contexto reativo, você deve mutar suas propriedades. Você nunca deve reatribuir o objeto inteiro.

Essa regra é inegociável. Viole-a e seus consumidores silenciosamente pararão de receber atualizações.

Entendendo a Mutação

Mutação significa alterar uma propriedade em um objeto existente — a identidade do objeto permanece a mesma, você está apenas mudando o que está dentro dele:

const user = $state({ name: 'Alice', score: 0 })

// ✅ Mutation: Changing existing properties
user.name = 'Bob'
user.score = 100

// ✅ Mutation: Adding new properties
user.email = 'bob@example.com'

// ✅ Mutation: Changing nested properties
user.settings = { theme: 'dark' }
user.settings.theme = 'light'

// ✅ Mutation: Array operations that modify in-place
user.friends = []
user.friends.push('Charlie')
user.friends.splice(0, 1)

Entendendo a Reatribuição

Reatribuição significa apontar a variável para um objeto completamente novo — isso é o que quebra o contexto:

let user = $state({ name: 'Alice', score: 0 })

// ❌ Reassignment: Creating a new object
user = { name: 'Bob', score: 100 }

// ❌ Reassignment: Even with spread operator
user = { ...user, score: 100 }

// ❌ Reassignment: Creating fresh object from JSON
user = JSON.parse(JSON.stringify(user))

// ❌ Reassignment: Filter/map/etc return new arrays
user.friends = user.friends.filter((f) => f !== 'Dave')

Após a reatribuição, a variável aponta para um objeto completamente diferente.

Por Que a Reatribuição Quebra o Contexto

Lembre-se: tanto o provedor quanto o consumidor guardam referências ao mesmo objeto. Quando você reatribui, você quebra essa referência compartilhada.

Com mutação (comportamento correto):

Before:
Provider.user ──────┐
                    ├──> { name: 'Alice', score: 0 }  (object at memory address 0x1234)
Consumer.user ──────┘

After user.score = 100:
Provider.user ──────┐
                    ├──> { name: 'Alice', score: 100 }  (same object at 0x1234, mutated)
Consumer.user ──────┘

Both still point to the same object. Consumer sees the change.

Com reatribuição (comportamento quebrado):

Before:
Provider.user ──────┐
                    ├──> { name: 'Alice', score: 0 }  (object at 0x1234)
Consumer.user ──────┘

After user = { name: 'Bob', score: 100 }:
Provider.user ──────────> { name: 'Bob', score: 100 }  (NEW object at 0x5678)

Consumer.user ──────────> { name: 'Alice', score: 0 }  (OLD object at 0x1234, orphaned!)

Consumer is now looking at an abandoned object. It will NEVER see updates again.

Um Cenário do Mundo Real: Provedor de Configurações

Vamos ver como isso funciona em um exemplo realista que você pode realmente precisar construir:

<!-- SettingsProvider.svelte -->
<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let settings = $state({
		theme: 'light',
		fontSize: 16,
		language: 'en',
		notifications: true
	})

	setContext('settings', settings)

	// ✅ CORRECT: Individual property changes
	function setDarkTheme() {
		settings.theme = 'dark'
	}

	function increaseFontSize() {
		settings.fontSize += 2
	}

	function toggleNotifications() {
		settings.notifications = !settings.notifications
	}

	// ❌ WRONG: Resetting by reassignment
	function resetSettingsBroken() {
		settings = { theme: 'light', fontSize: 16, language: 'en', notifications: true }
		// Provider now has a NEW object
		// All consumers still reference the OLD object
		// Future settings updates will NEVER reach consumers!
	}

	// ✅ CORRECT: Resetting by mutation
	function resetSettingsCorrect() {
		settings.theme = 'light'
		settings.fontSize = 16
		settings.language = 'en'
		settings.notifications = true
		// Same object, mutated properties
		// All consumers see the reset
	}

	// ✅ ALSO CORRECT: Using Object.assign
	function resetWithAssign() {
		Object.assign(settings, {
			theme: 'light',
			fontSize: 16,
			language: 'en',
			notifications: true
		})
		// Object.assign mutates the first argument
		// Same object, consumers see the change
	}
</script>

{@render children()}

Padrões Comuns que Acidentalmente Reatribuem

Fique atento a esses padrões que parecem inofensivos, mas quebram o contexto:

let state = $state({ items: [] })

// ❌ Spread into new object
state = { ...state, items: [...state.items, newItem] }

// ✅ Push into existing array
state.items.push(newItem)

// ❌ Filter returns new array, then reassigns
state.items = state.items.filter((i) => i.id !== id)

// ✅ In-place array mutation with splice
const index = state.items.findIndex((i) => i.id === id)
if (index !== -1) state.items.splice(index, 1)

// ❌ Map returns new array
state.items = state.items.map((i) => (i.id === id ? { ...i, done: true } : i))

// ✅ Find and mutate directly
const item = state.items.find((i) => i.id === id)
if (item) item.done = true

// ❌ Creating fresh object from fetch response
const data = await response.json()
state = data // Reassignment!

// ✅ Merging fetch data into existing object
const data = await response.json()
Object.assign(state, data)

Quando Você Precisa Substituir o Objeto Inteiro

Às vezes você legitimamente precisa substituir um objeto inteiro — por exemplo, substituir dados do usuário após o login. Nesse caso, envolva seus dados em um nível a mais:

<!-- UserProvider.svelte -->
<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	// Outer container NEVER gets reassigned
	let container = $state({
		user: null
	})

	setContext('user', container)

	async function login(credentials) {
		const response = await fetch('/api/login', {
			method: 'POST',
			body: JSON.stringify(credentials)
		})
		const userData = await response.json()

		// ✅ Mutating container.user property
		// Even though we're replacing the whole user object,
		// we're doing it by mutating the container
		container.user = userData
	}

	function logout() {
		// ✅ Mutating container.user property
		container.user = null
	}
</script>

{@render children()}

Os consumidores acessam via container.user:

<!-- UserDisplay.svelte -->
<script>
	import { getContext } from 'svelte'

	const userContext = getContext('user')
</script>

{#if userContext.user}
	<p>Welcome, {userContext.user.name}!</p>
	<p>Email: {userContext.user.email}</p>
{:else}
	<p>Please log in</p>
{/if}

O contêiner externo permanece o mesmo; você substitui o que está dentro dele. A cadeia de referências permanece intacta.

Avançando para Getters: A Conexão com Reatividade

Você dominou o padrão básico de objetos $state. Agora vamos explorar uma abordagem mais elegante que você verá em código de produção: funções getter. Entender por que getters funcionam desbloqueia APIs de contexto mais limpas e flexíveis.

O Problema com Atribuição Direta de Propriedade

Considere esta configuração de contexto aparentemente razoável:

<!-- ThemeProvider.svelte -->
<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let theme = $state('light')

	// ❌ This looks right but captures the VALUE at this moment
	setContext('theme', {
		current: theme, // Captures 'light' forever!
		toggle() {
			theme = theme === 'light' ? 'dark' : 'light'
		}
	})
</script>

{@render children()}

Quando esse código é executado, current recebe o valor 'light' — uma string primitiva. Mesmo quando theme muda para 'dark', current ainda mantém 'light':

<!-- ThemeToggle.svelte -->
<script>
	import { getContext } from 'svelte'

	const theme = getContext('theme')
</script>

<button onclick={theme.toggle}> Toggle Theme </button>

<p>Current: {theme.current}</p>
<!-- Always 'light', even after toggling! -->

A função de alternância funciona — ela muda a variável theme no provedor. Mas theme.current está congelado porque capturou um valor primitivo no momento da criação do objeto, não uma referência viva.

A Solução com Getter

Um getter é uma função que é executada cada vez que você acessa a propriedade. Ele lê o estado reativo de forma atualizada, retornando qualquer que seja o valor atual:

<!-- ThemeProvider.svelte -->
<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let theme = $state('light')

	// ✅ Getter reads the CURRENT value each time it's accessed
	setContext('theme', {
		get current() {
			return theme // Evaluates `theme` each time you read `current`
		},
		toggle() {
			theme = theme === 'light' ? 'dark' : 'light'
		}
	})
</script>

{@render children()}

Agora, quando os consumidores acessam theme.current, o JavaScript chama a função getter, que lê o valor atual da variável $state. Se o estado mudou, você obtém o novo valor.

Comparação Visual

WITHOUT GETTER (property assignment):
┌──────────────────────┐     setContext     ┌──────────────────────────────┐
│ let theme = 'light'  │ ────────────────>  │ { current: 'light' }         │
│                      │                    │                              │
│ theme = 'dark'       │    (later)         │ { current: 'light' }  ← STALE!
└──────────────────────┘                    └──────────────────────────────┘

WITH GETTER:
┌──────────────────────┐     setContext     ┌──────────────────────────────┐
│ let theme = $state() │ ────────────────>  │ { get current() {            │
│                      │                    │     return theme;            │
│ (every read of       │                    │   }                          │
│  theme.current)──────│────────────────────│───> runs getter, returns     │
│                      │                    │       current theme value    │
└──────────────────────┘                    └──────────────────────────────┘

Sistema de Tema Completo com Getters

Aqui está um exemplo completo mostrando o padrão getter em ação:

<!-- ThemeProvider.svelte -->
<script>
	import { setContext } from 'svelte'

	let { initialTheme = 'light', children } = $props()

	let theme = $state(initialTheme)

	// Context object with getters for reactive access
	const themeContext = {
		// Getter: reads fresh value each time
		get current() {
			return theme
		},

		// Getter: computed property
		get isDark() {
			return theme === 'dark'
		},

		// Getter: another computed property
		get cssClass() {
			return `theme-${theme}`
		},

		// Actions: methods that mutate state
		set(newTheme) {
			theme = newTheme
		},

		toggle() {
			theme = theme === 'light' ? 'dark' : 'light'
		}
	}

	setContext('theme', themeContext)

	// Side effect: apply theme to document
	$effect(() => {
		document.documentElement.setAttribute('data-theme', theme)
	})
</script>

{@render children()}

<!-- ThemeToggle.svelte -->
<script>
	import { getContext } from 'svelte'

	const theme = getContext('theme')
</script>

<button onclick={theme.toggle}>
	{theme.isDark ? '☀️ Switch to Light' : '🌙 Switch to Dark'}
</button>

<p>Current theme: {theme.current}</p>

<!-- ThemedCard.svelte -->
<script>
	import { getContext } from 'svelte'

	let { children } = $props()

	const theme = getContext('theme')
</script>

<div class="card" class:dark={theme.isDark}>
	{@render children()}
</div>

<style>
	.card {
		background: white;
		color: black;
		padding: 1rem;
		border-radius: 8px;
		transition:
			background 0.2s,
			color 0.2s;
	}

	.card.dark {
		background: #1a1a1a;
		color: white;
	}
</style>

Todos os consumidores reagem às mudanças de tema automaticamente porque acessam theme.current, theme.isDark e theme.cssClass por meio de getters que leem o $state reativo.

Getters vs Mutação de Objeto: Quando Usar Cada Um

Ambos os padrões funcionam para contexto reativo, mas têm pontos fortes diferentes:

Padrão de mutação de objeto (mais simples, acesso direto ao estado):

<script>
	let state = $state({ theme: 'light', fontSize: 16 })
	setContext('settings', state)

	// Consumers read: settings.theme, settings.fontSize
	// Provider updates: state.theme = 'dark'
</script>

Melhor quando:

Seu contexto é um contêiner de dados simples
Os consumidores precisam de acesso direto a todas as propriedades
Você não precisa de valores computados/derivados

Padrão getter (mais controle, encapsulamento):

<script>
	let theme = $state('light')
	let fontSize = $state(16)

	setContext('settings', {
		get theme() {
			return theme
		},
		get fontSize() {
			return fontSize
		},
		get isDark() {
			return theme === 'dark'
		}, // Computed!
		setTheme(t) {
			theme = t
		},
		increaseFontSize() {
			fontSize += 2
		}
	})
</script>

Melhor quando:

Você precisa de propriedades computadas/derivadas (como isDark)
Você quer ocultar a estrutura interna do estado
Você quer controlar como o estado é modificado (apenas via métodos)
Você tem múltiplas variáveis de estado relacionadas que não devem ser todas expostas diretamente

Evitando o Uso Excessivo de $effect

Um erro comum é usar $effect para "sincronizar" valores de contexto. Isso quase sempre está errado. Entender quando $effect é apropriado — e quando não é — vai ajudá-lo a escrever código mais limpo e previsível.

O Jeito Errado: Sincronizando com $effect

<script>
	import { setContext } from 'svelte'

	let { user } = $props()

	let contextUser = $state(user)

	// ❌ Don't do this!
	$effect(() => {
		contextUser = user // Trying to "sync" props to context
	})

	setContext('user', {
		get current() {
			return contextUser
		}
	})
</script>

Por Que Isso Está Errado

Esse padrão tem múltiplos problemas:

Indireção extra — Você está criando uma cópia do estado que espelha outro
Problemas de temporização — Os efeitos são executados após a renderização, causando possível oscilação visual
Complexidade desnecessária — Existe uma solução muito mais simples
Possíveis loops infinitos — Em casos complexos, você pode criar atualizações circulares

O Jeito Certo: Getter Direto

Se os dados vêm de props, basta usar a prop diretamente em um getter:

<script>
	import { setContext } from 'svelte'

	let { user, children } = $props()

	// ✅ Getter reads prop directly
	setContext('user', {
		get current() {
			return user
		}
	})
</script>

{@render children()}

Sem $state, sem $effect, apenas um getter que lê a prop. Quando user muda (porque o pai re-renderiza com novos dados), o getter retorna o novo valor automaticamente.

Quando $effect É Apropriado

Efeitos são para efeitos colaterais — coisas que acontecem fora do modelo de componentes do Svelte:

<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let theme = $state('light')

	setContext('theme', {
		get current() {
			return theme
		},
		set(value) {
			theme = value
		}
	})

	// ✅ Side effect: Update the DOM outside Svelte's control
	$effect(() => {
		document.documentElement.setAttribute('data-theme', theme)
	})

	// ✅ Side effect: Persist to localStorage
	$effect(() => {
		localStorage.setItem('theme', theme)
	})

	// ✅ Side effect: Log analytics
	$effect(() => {
		console.log('Theme changed to:', theme)
		// Or: analytics.track('theme_changed', { theme });
	})
</script>

{@render children()}

Use $effect quando você precisar:

Manipular o DOM diretamente
Interagir com APIs do navegador (localStorage, sessionStorage, etc.)
Chamar serviços ou APIs externas
Configurar assinaturas ou ouvintes de eventos
Realizar logging ou análises

O Modelo Mental de Três Camadas

Para solidificar sua compreensão, pense no contexto reativo em três camadas distintas:

┌─────────────────────────────────────────────────────────────┐
│  LAYER 1: STATE (The Source of Truth)                       │
│  ────────────────────────────────────                       │
│  $state variables hold the actual data                      │
│                                                             │
│  let theme = $state('light');                               │
│  let items = $state([]);                                    │
│  let settings = $state({ fontSize: 16, lang: 'en' });       │
│                                                             │
│  This is where data lives. Only one copy exists.            │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  LAYER 2: CONTEXT OBJECT (The API)                          │
│  ─────────────────────────────────                          │
│  Getters expose state, methods mutate it                    │
│                                                             │
│  setContext('app', {                                        │
│    get theme() { return theme; },                           │
│    get isDark() { return theme === 'dark'; },               │
│    setTheme(t) { theme = t; }                               │
│  });                                                        │
│                                                             │
│  This shapes what consumers see and how they interact.      │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  LAYER 3: CONSUMERS (The Users)                             │
│  ──────────────────────────────                             │
│  Read through getters, call methods, trigger UI updates     │
│                                                             │
│  const app = getContext('app');                             │
│  <p>{app.theme}</p>  <!-- Re-renders when theme changes --> │
│  <button onclick={() => app.setTheme('dark')}>Dark</button> │
│                                                             │
│  Components read and respond. They don't manage state.      │
└─────────────────────────────────────────────────────────────┘

Cada camada tem uma responsabilidade específica:

Camada 1 guarda a verdade — $state é a fonte única
Camada 2 molda a API — getters expõem o que os consumidores precisam, métodos controlam como o estado muda
Camada 3 consome reativamente — componentes leem e respondem às mudanças

Erros Comuns e Anti-Padrões

<script>
	let count = $state(0)
	setContext('count', count) // AVOID: Captures 0, not the reactive state
</script>

Por que quebra: Primitivos são copiados por valor. O contexto armazena o número 0, não uma referência ao seu $state.

Correção: Envolva em um objeto com um getter:

<script>
	let count = $state(0)
	setContext('count', {
		get value() {
			return count
		},
		set(v) {
			count = v
		}
	})
</script>

<script>
	let state = $state({ count: 0 })
	setContext('counter', state)

	function reset() {
		// ❌ This breaks the reference!
		state = { count: 0 }
	}
</script>

Por que quebra: O contexto guarda uma referência ao objeto original. Quando você reatribui state, cria um novo objeto. O contexto ainda aponta para o antigo.

Correção: Mute o objeto existente:

<script>
	function reset() {
		state.count = 0 // ✅ Mutate the property
	}
</script>

<script>
	let state = $state({ items: [1, 2, 3] })
	setContext('list', state)

	function removeFirst() {
		// ❌ filter() returns a NEW array
		state.items = state.items.filter((_, i) => i !== 0)
	}
</script>

Por que quebra: Embora você esteja mutando state.items (o que é correto), você está substituindo a referência do array. Isso funciona para consumidores diretos de state.items, mas se algum consumidor tiver armazenado em cache uma referência ao array antigo, ele terá dados desatualizados.

Correção: Use mutação in-place:

<script>
	function removeFirst() {
		state.items.splice(0, 1) // ✅ Mutates array in place
	}
</script>

<script>
	let { user } = $props()
	let contextUser = $state(user)

	// ❌ Don't do this!
	$effect(() => {
		contextUser = user // Trying to "sync" props to context
	})

	setContext('user', {
		get current() {
			return contextUser
		}
	})
</script>

Por que está errado: Indireção extra, problemas de temporização (efeitos são executados após a renderização) e complexidade desnecessária.

Correção: Use um getter que leia a prop diretamente:

<script>
	let { user } = $props()

	// ✅ Getter reads prop directly
	setContext('user', {
		get current() {
			return user
		}
	})
</script>

Verificando Seu Entendimento

Vamos testar sua compreensão desses conceitos. Para cada cenário, preveja se o consumidor receberá as atualizações.

Cenário 1

<!-- Provider -->
<script>
  let data = $state({ count: 0 });
  setContext('data', data);

  function increment() {
    data.count++;
  }
</script>

<!-- Consumer -->
<script>
  const data = getContext('data');
</script>
<p>{data.count}</p>

Resposta: ✅ Sim, atualiza. data.count++ muta o objeto existente. Tanto o provedor quanto o consumidor referenciam o mesmo objeto $state.

Cenário 2

<!-- Provider -->
<script>
  let count = $state(0);
  setContext('count', count);

  function increment() {
    count++;
  }
</script>

<!-- Consumer -->
<script>
  const count = getContext('count');
</script>
<p>{count}</p>

Resposta: ❌ Não, não atualiza. Primitivos são copiados por valor. O consumidor recebeu 0 na inicialização e nunca vê as mudanças.

Cenário 3

<!-- Provider -->
<script>
  let user = $state({ name: 'Alice' });
  setContext('user', user);

  function changeName() {
    user = { name: 'Bob' };  // Reassignment
  }
</script>

<!-- Consumer -->
<script>
  const user = getContext('user');
</script>
<p>{user.name}</p>

Resposta: ❌ Não, não atualiza. A reatribuição cria um novo objeto. O consumidor ainda referencia o objeto antigo que exibe 'Alice'.

Cenário 4

<!-- Provider -->
<script>
  let user = $state({ name: 'Alice' });
  setContext('user', user);

  function changeName() {
    user.name = 'Bob';  // Mutation
  }
</script>

<!-- Consumer -->
<script>
  const user = getContext('user');
</script>
<p>{user.name}</p>

Resposta: ✅ Sim, atualiza. user.name = 'Bob' muta o objeto existente. Ambos ainda referenciam o mesmo objeto.

Cenário 5

<!-- Provider -->
<script>
  let theme = $state('light');
  setContext('theme', {
    get current() { return theme; },
    toggle() { theme = theme === 'light' ? 'dark' : 'light'; }
  });
</script>

<!-- Consumer -->
<script>
  const theme = getContext('theme');
</script>
<p>{theme.current}</p>

Resposta: ✅ Sim, atualiza. O getter lê theme novamente a cada vez. Quando toggle() altera theme, a próxima leitura de theme.current retorna o novo valor.

Exemplo Completo de Produção

Vamos juntar tudo em um exemplo abrangente — um rastreador de pontuação que demonstra todos os padrões que cobrimos usando o padrão de getter.

<!-- ScoreProvider.svelte -->
<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	// Layer 1: State (source of truth)
	let points = $state(0)
	let multiplier = $state(1)
	let history = $state([])

	// Layer 2: Context object (the API)
	const scoreContext = {
		// Getters for reactive access
		get points() {
			return points
		},

		get multiplier() {
			return multiplier
		},

		get history() {
			return history
		},

		// Computed properties via getters
		get totalWithMultiplier() {
			return points * multiplier
		},

		get hasHistory() {
			return history.length > 0
		},

		// Methods for controlled mutations
		addPoints(amount) {
			const earned = amount * multiplier
			points += earned
			history.push({
				timestamp: Date.now(),
				amount: earned,
				total: points
			})
		},

		doubleMultiplier() {
			multiplier *= 2
		},

		reset() {
			points = 0
			multiplier = 1
			history.length = 0 // Clear array in place
		}
	}

	setContext('score', scoreContext)
</script>

{@render children()}

<!-- ScoreDisplay.svelte -->
<script>
	import { getContext } from 'svelte'

	const score = getContext('score')
</script>

<div class="score-display">
	<h2>Score: {score.points}</h2>
	<p>Multiplier: {score.multiplier}×</p>
	<p>Effective total: {score.totalWithMultiplier}</p>
</div>

<style>
	.score-display {
		padding: 1rem;
		background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
		color: white;
		border-radius: 8px;
		text-align: center;
	}

	h2 {
		margin: 0 0 0.5rem;
		font-size: 2rem;
	}

	p {
		margin: 0.25rem 0;
		opacity: 0.9;
	}
</style>

<!-- ScoreControls.svelte -->
<script>
	import { getContext } from 'svelte'

	const score = getContext('score')
</script>

<div class="controls">
	<button onclick={() => score.addPoints(10)}>+10 points</button>
	<button onclick={() => score.addPoints(50)}>+50 points</button>
	<button onclick={() => score.doubleMultiplier()}>Double Multiplier</button>
	<button onclick={() => score.reset()} class="reset">Reset</button>
</div>

<style>
	.controls {
		display: flex;
		gap: 0.5rem;
		flex-wrap: wrap;
	}

	button {
		padding: 0.5rem 1rem;
		border: none;
		border-radius: 4px;
		background: #3b82f6;
		color: white;
		cursor: pointer;
		font-weight: 500;
	}

	button:hover {
		background: #2563eb;
	}

	button.reset {
		background: #ef4444;
	}

	button.reset:hover {
		background: #dc2626;
	}
</style>

<!-- ScoreHistory.svelte -->
<script>
	import { getContext } from 'svelte'

	const score = getContext('score')

	function formatTime(timestamp) {
		return new Date(timestamp).toLocaleTimeString()
	}
</script>

<div class="history">
	<h3>History ({score.history.length} entries)</h3>

	{#if score.hasHistory}
		<ul>
			{#each score.history as entry, i (entry.timestamp)}
				<li>
					<span class="index">#{i + 1}</span>
					<span class="amount">+{entry.amount}</span>
					<span class="total">→ {entry.total} total</span>
					<span class="time">{formatTime(entry.timestamp)}</span>
				</li>
			{/each}
		</ul>
	{:else}
		<p class="empty">No points scored yet</p>
	{/if}
</div>

<style>
	.history {
		padding: 1rem;
		background: #f3f4f6;
		border-radius: 8px;
	}

	h3 {
		margin: 0 0 0.75rem;
		color: #374151;
	}

	ul {
		list-style: none;
		padding: 0;
		margin: 0;
	}

	li {
		display: flex;
		gap: 0.75rem;
		padding: 0.5rem 0;
		border-bottom: 1px solid #e5e7eb;
		font-size: 0.875rem;
	}

	li:last-child {
		border-bottom: none;
	}

	.index {
		color: #9ca3af;
		font-weight: 500;
	}

	.amount {
		color: #059669;
		font-weight: 600;
	}

	.total {
		color: #374151;
	}

	.time {
		margin-left: auto;
		color: #9ca3af;
		font-size: 0.75rem;
	}

	.empty {
		color: #9ca3af;
		font-style: italic;
		margin: 0;
	}
</style>

<!-- +page.svelte -->
<script>
	import ScoreProvider from './ScoreProvider.svelte'
	import ScoreDisplay from './ScoreDisplay.svelte'
	import ScoreControls from './ScoreControls.svelte'
	import ScoreHistory from './ScoreHistory.svelte'
</script>

<ScoreProvider>
	<main>
		<h1>Score Tracker</h1>
		<ScoreDisplay />
		<ScoreControls />
		<ScoreHistory />
	</main>
</ScoreProvider>

<style>
	main {
		max-width: 600px;
		margin: 2rem auto;
		padding: 1rem;
		display: flex;
		flex-direction: column;
		gap: 1rem;
	}

	h1 {
		text-align: center;
		color: #1f2937;
	}
</style>

Todos os três componentes consumidores compartilham o mesmo contexto. Quando ScoreControls chama score.addPoints(), tanto ScoreDisplay quanto ScoreHistory são re-renderizados automaticamente para exibir os valores atualizados.

Tabela de Referência Rápida

Padrão	Funciona?	Por quê
`$state({ value: 0 })` + `value++`	✅	Mutação de objeto, Svelte rastreia
`$state(0)` diretamente no context	❌	Primitivo copiado por valor
`object.property = newValue`	✅	Mutação preserva a referência
`object = { ...object }`	❌	Reatribuição quebra a referência
`array.push(item)`	✅	Mutação in-place
`array = array.filter(...)`	❌	Cria um novo array
`array.splice(index, 1)`	✅	Mutação in-place
`Object.assign(obj, newData)`	✅	Muta o primeiro argumento
`get prop() { return $state }`	✅	Getter lê o valor atualizado
`prop: $state` em object literal	❌	Captura o valor no momento da criação

Considerações de Desempenho e Escalabilidade

O contexto reativo é eficiente, mas entender suas características de desempenho ajuda você a escalar com confiança.

Atualizações Granulares

A reatividade do Svelte é granular. Quando você muta uma propriedade específica, apenas os componentes que leem aquele valor específico são re-renderizados—não todos os componentes que leem qualquer parte do objeto de contexto. Isso significa que você pode ter objetos de estado complexos sem se preocupar com atualizações em cascata.

Arrays e Objetos Grandes

Para arrays grandes (centenas ou milhares de itens), considere usar um Map para busca O(1) em vez de iterar:

<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let items = $state([])
	let itemsById = new Map()

	const listContext = {
		get items() {
			return items
		},

		add(item) {
			items.push(item)
			itemsById.set(item.id, item)
		},

		getById(id) {
			return itemsById.get(id)
		},

		updateById(id, updates) {
			const item = itemsById.get(id)
			if (item) {
				Object.assign(item, updates) // Mutate in place
			}
		}
	}

	setContext('list', listContext)
</script>

{@render children()}

Considerações de Memória

Objetos de contexto persistem durante o tempo de vida do componente provedor. Se você estiver armazenando grandes quantidades de dados, considere estratégias de limpeza:

<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let cache = $state(new Map())
	const maxSize = 100

	const cacheContext = {
		set(key, value) {
			// Evict oldest if at capacity
			if (cache.size >= maxSize) {
				const firstKey = cache.keys().next().value
				cache.delete(firstKey)
			}
			cache.set(key, value)
		},

		get(key) {
			return cache.get(key)
		}
	}

	setContext('cache', cacheContext)
</script>

{@render children()}

Conclusão

Contexto reativo não é mágica—é a consequência natural de entender como o JavaScript lida com valores e como o Svelte rastreia mudanças. Quando você vê o contexto "não funcionando", quase sempre está vendo uma de duas coisas: primitivos sendo copiados por valor em vez de referenciados, ou uma reatribuição quebrando referências compartilhadas.

O padrão de objeto com $state resolve ambos os problemas de forma elegante. Ao envolver seus dados em um objeto e compartilhar esse objeto pelo contexto, você estabelece uma única fonte de verdade que múltiplos componentes podem tanto ler quanto modificar. O sistema de reatividade do Svelte cuida do resto—rastreando quais componentes dependem de quais propriedades e re-renderizando-os quando essas propriedades mudam.

O padrão de getter vai além, permitindo que você exponha propriedades computadas e oculte detalhes internos de implementação enquanto mantém APIs limpas e previsíveis.

A regra de ouro de "mutar, não reatribuir" pode parecer restritiva no início, mas na verdade é libertadora quando você a internaliza. Você nunca precisa se perguntar se o seu contexto está sincronizado entre os componentes. Enquanto você estiver mutando o mesmo objeto, todos veem os mesmos dados. É um modelo mental simples que escala desde contadores triviais até estados de aplicação complexos.

Com esses fundamentos estabelecidos, você está preparado para construir contextos que permanecem sincronizados em toda a sua árvore de componentes—a base para tudo, desde sistemas de temas até carrinhos de compras e funcionalidades de colaboração em tempo real.

Principais Conclusões

Contexto simples captura um instantâneo. Quando você chama setContext(key, value), o Svelte armazena aquele valor como está. Para primitivos, isso é uma cópia. Para objetos, é uma referência. De qualquer forma, não há uma conexão contínua—alterações na variável original não atualizam automaticamente o valor armazenado.

$state com objetos cria reatividade. Ao envolver seus dados em um objeto $state e compartilhar esse objeto via contexto, tanto o provedor quanto o consumidor mantêm referências ao mesmo objeto reativo. Quando você muta as propriedades do objeto, o Svelte rastreia a mudança e atualiza todos os componentes que leem essas propriedades.

Mute propriedades, nunca reatribua o objeto. Esta é a regra de ouro. A mutação preserva a referência compartilhada. A reatribuição cria um novo objeto, deixando os consumidores com uma referência órfã aos dados antigos. Sempre altere propriedades (obj.prop = newValue), nunca substitua o objeto inteiro (obj = newObject).

Getters garantem atualidade. Use funções getter (get prop()) quando você precisar de valores computados ou quando quiser encapsular estado interno. Getters são executados a cada acesso, sempre retornando o valor atual.

Evite $effect para sincronização. Se os dados vêm de props, use um getter. Reserve $effect para efeitos colaterais reais como manipulação do DOM, persistência no localStorage ou chamadas a APIs externas.

Pense em três camadas. Estado (fonte de verdade) → Objeto de Contexto (a API) → Consumidores (os usuários). Cada camada tem uma função específica, e mantê-las separadas torna seu código sustentável.

O Que Vem a Seguir

Construa sobre esses fundamentos com padrões avançados em Contexto Baseado em Classes, onde você aprenderá a usar classes TypeScript com $state para um contexto encapsulado e type-safe que escala para aplicações complexas.

Veja Também

Documentação Oficial

$state — Rune de estado reativo
Svelte Context — Guia oficial de contexto