Quando APIs Simples Te Pegam de Surpresa

Mesmo desenvolvedores experientes em Svelte ocasionalmente tropeçam com contexto. A API é simples na superfície—apenas setContext e getContext—mas comportamentos sutis podem levar a bugs confusos. Valores que não atualizam. Contexto que misteriosamente retorna undefined. Componentes que lançam erros sobre o momento de inicialização.

Este artigo cataloga as armadilhas de contexto mais comuns, explica por que elas ocorrem e fornece soluções claras. Também abordaremos técnicas de depuração para diagnosticar rapidamente problemas de contexto quando eles surgirem. Considere este seu guia de solução de problemas para tudo relacionado a contexto.

Ao entender essas armadilhas, você escreverá código de contexto mais robusto e gastará menos tempo depurando falhas misteriosas.

Armadilha 1: Chamando Funções de Contexto Fora da Inicialização

O erro mais comum: tentar chamar setContext ou getContext fora da inicialização do componente.

O Erro

Error: `setContext(...)` can only be called during component initialization
Error: `getContext(...)` can only be called during component initialization

O Que Causa Isso

As funções de contexto devem ser chamadas durante a execução síncrona do seu bloco <script> quando o componente é montado pela primeira vez. Elas não podem ser chamadas em:

Manipuladores de eventos
Callbacks de $effect
Callbacks de setTimeout ou setInterval
Callbacks de .then() de Promises
Após uma instrução await
Qualquer código assíncrono

Exemplos do Erro

<script>
	import { setContext, getContext } from 'svelte'

	// ❌ Inside event handler
	function handleClick() {
		setContext('late', 'value') // Error!
	}

	// ❌ Inside effect
	$effect(() => {
		const value = getContext('something') // Error!
	})

	// ❌ Inside setTimeout
	setTimeout(() => {
		setContext('delayed', 'value') // Error!
	}, 0)

	// ❌ After await
	async function setup() {
		const data = await fetch('/api/data')
		setContext('data', data) // Error!
	}
	setup()

	// ❌ In Promise callback
	fetch('/api/config')
		.then((response) => response.json())
		.then((config) => {
			setContext('config', config) // Error!
		})
</script>

A Solução

Sempre capture ou defina o contexto no nível superior do seu script, depois use os valores capturados em outros lugares:

<script>
	import { setContext, getContext } from 'svelte'

	// ✅ Set context during initialization with reactive state
	let config = $state(null)
	let loading = $state(true)

	setContext('config', {
		get data() {
			return config
		},
		get loading() {
			return loading
		}
	})

	// ✅ Capture context during initialization
	const theme = getContext('theme')
	const auth = getContext('auth')

	// Now use freely in event handlers
	function handleClick() {
		console.log('Theme:', theme.mode) // ✅ Works!
		console.log('User:', auth.user?.name) // ✅ Works!
	}

	// And in effects
	$effect(() => {
		document.body.classList.toggle('dark', theme.isDark) // ✅ Works!
	})

	// And with async operations
	async function loadConfig() {
		loading = true
		const response = await fetch('/api/config')
		config = await response.json() // Updates the context value!
		loading = false
	}
	loadConfig()
</script>

Por Que Essa Restrição Existe

O contexto faz parte da estrutura da árvore de componentes. Quando um componente filho é inicializado, ele percorre a árvore em busca do contexto que os ancestrais definiram. Se o contexto pudesse ser definido posteriormente (em manipuladores de eventos, etc.), os filhos já teriam tentado lê-lo e falhado.

Pense nisso como construir uma casa: você precisa instalar a encanação (contexto) enquanto constrói as paredes (inicialização do componente), não depois que a casa estiver pronta (em tempo de execução).

Armadilha 2: Reatribuindo Objetos de Estado

Uma das armadilhas mais complicadas: quebrar a conexão entre provedor e consumidores ao reatribuir o estado.

O Sintoma

As atualizações de contexto funcionam inicialmente, depois param de repente. Alguns consumidores veem as atualizações, outros não. Ou as atualizações param após uma ação específica.

O Que Causa Isso

Quando você fornece um objeto reativo via contexto, tanto o provedor quanto os consumidores mantêm referências ao mesmo objeto. Se você reatribuir a variável no provedor para um novo objeto, os consumidores ainda referenciam o objeto antigo.

O Erro

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

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

	function updateScore() {
		user.score++ // ✅ This works - mutating the object
	}

	function resetUser() {
		user = { name: 'Guest', score: 0 } // ❌ This breaks consumers!
		// Provider now points to NEW object
		// Consumers still point to OLD object
	}
</script>

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

	const user = getContext('user')
	// user references the ORIGINAL object
	// After resetUser(), this is orphaned
</script>

<p>{user.name}: {user.score}</p>
<!-- After resetUser(), still shows old values -->

Explicação Visual

Initial state:
Provider.user ───────┐
                     ├──> { name: 'Alice', score: 0 }
Consumer.user ───────┘

After user.score++ (mutation):
Provider.user ───────┐
                     ├──> { name: 'Alice', score: 1 }  ✅ Both see change
Consumer.user ───────┘

After user = { name: 'Guest', score: 0 } (reassignment):
Provider.user ───────────> { name: 'Guest', score: 0 }  ← NEW object

Consumer.user ───────────> { name: 'Alice', score: 1 }  ← OLD object (orphaned!)
                           ❌ Consumer never sees new object

A Solução

Sempre mute propriedades, nunca reatribua o objeto inteiro:

<script>
	import { setContext } from 'svelte'

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

	function updateScore() {
		user.score++ // ✅ Mutation
	}

	function resetUser() {
		// ✅ Mutate properties individually
		user.name = 'Guest'
		user.score = 0
	}

	// ✅ Or use Object.assign for multiple properties
	function updateUser(updates) {
		Object.assign(user, updates)
	}
</script>

Alternativa: Envolver em Objeto Contêiner

Se você precisar substituir o valor inteiro, envolva-o em um contêiner:

<script>
	import { setContext } from 'svelte'

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

	function resetUser() {
		// ✅ Mutating container.user property
		container.user = { name: 'Guest', score: 0 }
	}
</script>

O consumidor acessa via o contêiner:

<script>
	const container = getContext('userContainer')
</script>

<!-- Access through container --><p>{container.user.name}: {container.user.score}</p>

Armadilha 3: Desestruturando Valores Reativos

A desestruturação captura valores em um determinado momento, quebrando a reatividade.

O Sintoma

Variáveis de contexto desestruturado nunca atualizam, mesmo que a fonte mude.

O Erro

<script>
	import { getContext } from 'svelte'

	const settings = getContext('settings')

	// ❌ Destructuring captures current VALUES
	const { theme, fontSize, language } = settings
	// theme = 'light' (a string, frozen in time)
	// fontSize = 16 (a number, frozen in time)
</script>

<!-- These never update! -->
<div class={theme}>
	<!-- Always 'light' -->
	<p style="font-size: {fontSize}px">
		<!-- Always 16 -->
		{language}
		<!-- Always the initial value -->
	</p>
</div>

Por Que Isso Acontece

A desestruturação é açúcar sintático para atribuição:

const { theme } = settings
// Is equivalent to:
const theme = settings.theme // Copies the primitive value

Para primitivos (strings, números, booleanos), você obtém uma cópia. Para objetos, você obtém uma referência—mas ainda capturada naquele momento.

Soluções

Solução 1: Não desestruture, acesse diretamente

<script>
	const settings = getContext('settings')
	// Keep the object reference
</script>

<!-- Access properties directly - always current -->
<div class={settings.theme}>
	<p style="font-size: {settings.fontSize}px">
		{settings.language}
	</p>
</div>

Solução 2: "Desestruturação" reativa com $derived

<script>
	const settings = getContext('settings')

	// ✅ Each $derived re-evaluates when settings changes
	let theme = $derived(settings.theme)
	let fontSize = $derived(settings.fontSize)
	let language = $derived(settings.language)
</script>

<!-- Now these update! -->
<div class={theme}>
	<p style="font-size: {fontSize}px">
		{language}
	</p>
</div>

Solução 3: Desestruture apenas métodos

Métodos (funções) podem ser desestruturados com segurança—são referências, não valores:

<script>
	const cart = getContext('cart')

	// ✅ Safe - these are function references
	const { addItem, removeItem, clear } = cart

	function handleAdd(product) {
		addItem(product) // Works correctly
	}
</script>

Armadilha 4: Provider Ausente

Consumindo contexto que nunca foi fornecido.

O Sintoma

getContext retorna undefined, causando erros "Cannot read property X of undefined" quando você tenta usar o contexto.

O Erro

<!-- App.svelte - forgot the provider! -->
<script>
	import Dashboard from './Dashboard.svelte'
</script>

<!-- No AuthProvider wrapping Dashboard -->
<Dashboard />

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

	const auth = getContext('auth') // Returns undefined!

	// Later...
	console.log(auth.user.name) // Error: Cannot read property 'user' of undefined
</script>

Soluções

Solução 1: Verificar com hasContext

<script>
	import { getContext, hasContext } from 'svelte'

	if (!hasContext('auth')) {
		throw new Error('Auth context not found. ' + 'Wrap this component in an AuthProvider.')
	}

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

Solução 2: Fornecer valores padrão para contexto opcional

<script>
	import { getContext, hasContext } from 'svelte'

	const defaultAuth = {
		user: null,
		isAuthenticated: false,
		login: () => console.warn('No auth provider'),
		logout: () => console.warn('No auth provider')
	}

	const auth = hasContext('auth') ? getContext('auth') : defaultAuth
</script>

Solução 3: Usar createContext que lança exceção

Com o createContext do Svelte 5.40+, o getter lança automaticamente:

// auth.svelte.ts
import { createContext } from 'svelte'

export const [getAuth, setAuth] = createContext<AuthContext>()

// Consumer.svelte
const auth = getAuth() // Throws "Context was not provided" if missing

Solução 4: Criar um utilitário getter seguro

// lib/context/utils.ts
import { getContext, hasContext } from 'svelte'

export function requireContext<T>(key: any, name: string): T {
	if (!hasContext(key)) {
		throw new Error(
			`${name} context is required but was not found. ` +
				`Ensure this component is rendered inside the appropriate provider.`
		)
	}
	return getContext(key)
}

// Usage
const auth = requireContext('auth', 'Auth')

Armadilha 5: Provider na Posição Errada

O provider está presente, mas não é ancestral do consumidor.

O Sintoma

O contexto retorna undefined mesmo que o provider exista na aplicação.

O Erro

<!-- App.svelte -->
<script>
	import AuthProvider from './AuthProvider.svelte'
	import Dashboard from './Dashboard.svelte'
</script>

<!-- Provider and Dashboard are SIBLINGS, not parent-child -->
<AuthProvider />
<Dashboard />
<!-- Can't access auth context! -->

O contexto flui apenas para baixo, de ancestrais para descendentes. Componentes irmãos não podem ver o contexto uns dos outros.

A Solução

Certifique-se de que o provider envolva o consumidor:

<!-- App.svelte -->
<script>
	import AuthProvider from './AuthProvider.svelte'
	import Dashboard from './Dashboard.svelte'
</script>

<!-- Provider WRAPS Dashboard -->
<AuthProvider>
	<Dashboard />
	<!-- Now has access! -->
</AuthProvider>

Depuração Visual

❌ Wrong - siblings:
App
├── AuthProvider (sets 'auth')
└── Dashboard (getContext('auth') → undefined)

✅ Correct - ancestor/descendant:
App
└── AuthProvider (sets 'auth')
    └── Dashboard (getContext('auth') → ✓)

Armadilha 6: Chave Errada

Usando uma chave diferente no get em relação à usada no set.

O Sintoma

O contexto retorna undefined mesmo com o relacionamento correto entre provider e consumidor.

O Erro

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

	setContext('userAuth', authData)  // Key: 'userAuth'
</script>

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

	const auth = getContext('auth')  // Key: 'auth' ← Doesn't match!
	// Returns undefined
</script>

Isso é especialmente fácil de ocorrer com:

Erros de digitação: 'user' vs 'users'
Sensibilidade a maiúsculas: 'Auth' vs 'auth'
Convenções diferentes: 'user-auth' vs 'userAuth'

Soluções

Solução 1: Exportar a chave

// context/keys.ts
export const AUTH_KEY = 'auth'
export const CART_KEY = 'cart'
export const THEME_KEY = 'theme'

<!-- Both files import the same key -->
import {AUTH_KEY} from './context/keys' setContext(AUTH_KEY, value) // Provider getContext(AUTH_KEY)
// Consumer

Solução 2: Usar Symbols

Symbols são únicos, portanto colisões de chaves são impossíveis:

// context/auth.svelte.ts
const AUTH_KEY = Symbol('auth')

export function createAuthContext() {
	return setContext(AUTH_KEY /* ... */)
}

export function getAuthContext() {
	return getContext(AUTH_KEY)
}

Solução 3: Usar createContext

createContext gerencia chaves internamente:

// No key to get wrong!
export const [getAuth, setAuth] = createContext<AuthContext>()

Armadilha 7: Contexto em Componentes Dinâmicos

Componentes montados fora da árvore normal perdem o contexto.

O Sintoma

Componentes montados dinamicamente (modais, tooltips, portais) não conseguem acessar o contexto.

O Erro

<script>
	import { mount } from 'svelte'
	import Modal from './Modal.svelte'

	function openModal() {
		// Modal mounted at document.body, outside Svelte tree
		mount(Modal, { target: document.body })
		// Modal has NO access to any context!
	}
</script>

A Solução

Encaminhe o contexto explicitamente usando getAllContexts:

<script>
	import { mount, getAllContexts } from 'svelte'
	import Modal from './Modal.svelte'

	// Capture context during initialization
	const appContext = getAllContexts()

	function openModal() {
		mount(Modal, {
			target: document.body,
			context: appContext // Forward all context
		})
	}
</script>

Ou crie um componente portal que lide com isso:

<!-- Portal.svelte -->
<script>
	import { mount, unmount, getAllContexts } from 'svelte'

	let { target = document.body, children } = $props()

	const context = getAllContexts()

	$effect(() => {
		// Create a wrapper component that re-provides context
		const wrapper = mount(ContextForwarder, {
			target,
			context,
			props: { content: children }
		})

		return () => unmount(wrapper)
	})
</script>

Armadilha 8: Esperar Reatividade Sem $state

Objetos simples no contexto não são reativos.

O Sintoma

Os valores do contexto não são atualizados quando a fonte muda.

O Erro

<script>
	import { setContext } from 'svelte'

	// Plain object, not reactive
	const user = { name: 'Alice', score: 0 }
	setContext('user', user)

	function updateScore() {
		user.score++ // Value changes in memory...
		// But Svelte doesn't know! No re-renders triggered.
	}
</script>

A Solução

Use $state para valores de contexto reativos:

<script>
	import { setContext } from 'svelte'

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

	function updateScore() {
		user.score++ // ✅ Svelte tracks this, triggers re-renders
	}
</script>

Armadilha 9: Usar Contexto para Dados Sensíveis ao SSR

Mutações de contexto durante o SSR podem vazar entre requisições.

O Sintoma

Usuários veem dados de outros usuários. Dados persistem incorretamente entre requisições.

O Erro

// lib/stores/global.svelte.ts

// Global mutable state - DANGEROUS with SSR!
export const globalUser = $state({ name: null, id: null })

<!-- +page.svelte -->
<script>
	import { globalUser } from '$lib/stores/global.svelte'

	let { data } = $props()

	// Mutating global state during render
	globalUser.name = data.user.name // ❌ May leak to other requests!
</script>

No servidor, um único processo Node.js lida com múltiplas requisições. O estado global persiste entre as requisições.

A Solução

Use contexto para dados com escopo de requisição:

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

	let { data } = $props()

	// Create fresh context for each request
	// Context is automatically isolated per-component-tree
	setContext('user', data.user)
</script>

<slot />

O contexto está vinculado a uma árvore de componentes específica. Cada requisição recebe sua própria árvore de componentes, portanto o contexto é naturalmente isolado.

Armadilha 10: Contexto em Loops Intensos

Acessar o contexto repetidamente em loops ou em funções chamadas com frequência.

O Sintoma

Desempenho lento da interface quando muitos componentes consomem o mesmo contexto, ou quando funções dependentes de contexto são chamadas com frequência.

O Erro

<script>
	import { getContext } from 'svelte'

	let { items } = $props()

	// ❌ Getting context inside a function called per item
	function formatItem(item) {
		const settings = getContext('settings') // Called many times!
		return `${item.name} (${settings.currency})`
	}
</script>

{#each items as item}
	<p>{formatItem(item)}</p>
{/each}

Embora getContext seja rápido, chamá-lo repetidamente em loops adiciona uma sobrecarga desnecessária. Mais importante ainda, esse padrão sugere uma incompreensão de como o contexto funciona — você só precisa obtê-lo uma vez.

A Solução

Obtenha o contexto uma vez no nível superior do seu script:

<script>
	import { getContext } from 'svelte'

	let { items } = $props()

	// ✅ Get context once during initialization
	const settings = getContext('settings')

	function formatItem(item) {
		return `${item.name} (${settings.currency})`
	}
</script>

{#each items as item (item.id)}
	<p>{formatItem(item)}</p>
{/each}

O valor do contexto não muda durante o ciclo de vida do componente (embora suas propriedades possam mudar se ele for reativo). Capture a referência uma vez e reutilize-a em todo o seu componente.

Padrão Relacionado: Evitar Contexto em Valores Derivados

Não acesse contexto dentro de cálculos $derived que são executados com frequência:

<script>
	import { getContext } from 'svelte'

	let { price } = $props()

	// ❌ Context access inside derived (works but unclear intent)
	let formatted = $derived(() => {
		const settings = getContext('settings')
		return new Intl.NumberFormat(settings.locale, {
			style: 'currency',
			currency: settings.currency
		}).format(price)
	})
</script>

<script>
	import { getContext } from 'svelte'

	let { price } = $props()

	// ✅ Get context at top level, use in derived
	const settings = getContext('settings')

	let formatted = $derived(
		new Intl.NumberFormat(settings.locale, {
			style: 'currency',
			currency: settings.currency
		}).format(price)
	)
</script>

Ambos funcionam, mas a segunda versão torna o fluxo de dados mais claro e segue o padrão estabelecido de capturar o contexto durante a inicialização.

Técnicas de Depuração

Quando o contexto não está funcionando, essas técnicas ajudam a diagnosticar o problema.

Técnica 1: Componente Inspetor de Contexto

Crie um componente que exiba todo o contexto disponível:

<!-- ContextDebugger.svelte -->
<script>
	import { getAllContexts } from 'svelte'

	let { show = true } = $props()

	const contexts = getAllContexts()

	function formatValue(value) {
		if (value === undefined) return 'undefined'
		if (value === null) return 'null'
		if (typeof value === 'function') return '[Function]'
		try {
			return JSON.stringify(value, null, 2)
		} catch {
			return String(value)
		}
	}

	function formatKey(key) {
		if (typeof key === 'symbol') {
			return key.toString()
		}
		return String(key)
	}
</script>

{#if show && import.meta.env.DEV}
	<details class="context-debugger" open>
		<summary>🔍 Context ({contexts.size} keys)</summary>

		{#if contexts.size === 0}
			<p class="empty">No context available at this position</p>
		{:else}
			<ul>
				{#each [...contexts.entries()] as [key, value] (key)}
					<li>
						<strong class="key">{formatKey(key)}</strong>
						<pre class="value">{formatValue(value)}</pre>
					</li>
				{/each}
			</ul>
		{/if}
	</details>
{/if}

<style>
	.context-debugger {
		position: fixed;
		bottom: 1rem;
		right: 1rem;
		background: #1e1e2e;
		color: #cdd6f4;
		padding: 0.75rem;
		border-radius: 8px;
		font-family: 'Fira Code', monospace;
		font-size: 12px;
		max-width: 400px;
		max-height: 400px;
		overflow: auto;
		z-index: 9999;
		box-shadow: 0 4px 20px rgba(0, 0, 0, 0.3);
	}

	summary {
		cursor: pointer;
		font-weight: bold;
		padding: 0.25rem 0;
	}

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

	li {
		padding: 0.5rem;
		border-bottom: 1px solid #313244;
	}

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

	.key {
		color: #89b4fa;
	}

	.value {
		margin: 0.25rem 0 0;
		padding: 0.5rem;
		background: #313244;
		border-radius: 4px;
		white-space: pre-wrap;
		word-break: break-all;
		color: #a6e3a1;
	}

	.empty {
		color: #f38ba8;
		font-style: italic;
	}
</style>

Solte isso em qualquer lugar para ver qual contexto está disponível:

<!-- SomeDeeplyNestedComponent.svelte -->
<script>
	import ContextDebugger from '$lib/debug/ContextDebugger.svelte'
</script>

<div>
	<!-- Component content -->
</div>

<ContextDebugger />

Técnica 2: Console Logging em Providers

Adicione logging de desenvolvimento para rastrear a configuração do contexto:

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

	let { children } = $props()

	let user = $state(null)

	const context = {
		get user() {
			return user
		},
		get isAuthenticated() {
			return user !== null
		}
	}

	setContext('auth', context)

	// Development logging
	if (import.meta.env.DEV) {
		console.log('🔐 AuthProvider: Context set', context)

		$effect(() => {
			console.log('🔐 AuthProvider: User changed', user)
		})
	}
</script>

{@render children()}

Técnica 3: Rastreamento da Pilha de Providers

Rastreie a hierarquia de providers:

<!-- Add to each provider -->
<script>
	import { setContext, getContext, hasContext } from 'svelte'

	// Track provider stack
	const parentStack = hasContext('__debug_providers') ? getContext('__debug_providers') : []

	const myStack = [...parentStack, 'AuthProvider']
	setContext('__debug_providers', myStack)

	if (import.meta.env.DEV) {
		console.log('Provider stack:', myStack.join(' → '))
	}
</script>

Saída:

Provider stack: ThemeProvider → AuthProvider
Provider stack: ThemeProvider → AuthProvider → CartProvider

Técnica 4: Verificando a Posição do Consumer

Verifique onde na árvore um consumer está:

<script>
	import { getContext, hasContext, getAllContexts } from 'svelte'

	const available = getAllContexts()
	const hasAuth = hasContext('auth')
	const hasTheme = hasContext('theme')

	if (import.meta.env.DEV) {
		console.group('Component: UserProfile')
		console.log('Available context keys:', [...available.keys()])
		console.log('Has auth context:', hasAuth)
		console.log('Has theme context:', hasTheme)
		console.groupEnd()
	}
</script>

Técnica 5: Envolvimento com Error Boundary

Capture erros de contexto de forma elegante:

<!-- SafeContextConsumer.svelte -->
<script>
	import { getContext, hasContext } from 'svelte'

	let { contextKey, fallback, children } = $props()

	let error = null
	let context = null

	try {
		if (!hasContext(contextKey)) {
			throw new Error(`Context '${contextKey}' not found`)
		}
		context = getContext(contextKey)
	} catch (e) {
		error = e.message
		if (import.meta.env.DEV) {
			console.error(`Context error: ${e.message}`)
		}
	}
</script>

{#if error}
	{#if fallback}
		{@render fallback(error)}
	{:else}
		<div class="context-error">
			Context Error: {error}
		</div>
	{/if}
{:else}
	{@render children(context)}
{/if}

Referência Rápida: Sintomas e Soluções

Sintoma	Causa Provável	Solução
"can only be called during initialization"	Função de contexto em código assíncrono	Chame no nível superior, capture o valor
Contexto retorna `undefined`	Provider ausente	Adicione o provider como ancestral
Contexto retorna `undefined`	Chave errada	Use chaves compartilhadas, Symbols ou createContext
Contexto retorna `undefined`	Provider é irmão, não ancestral	Reestruture para envolver o consumer
Valores não atualizam	Objeto simples, não `$state`	Use `$state` para valores reativos
Valores param de atualizar após certa ação	Objeto de estado reatribuído	Mute propriedades, não reatribua
Valores desestruturados não atualizam	Valores primitivos capturados	Acesse via objeto ou use `$derived`
Modal/portal não consegue acessar o contexto	Montado fora da árvore	Encaminhe o contexto com `getAllContexts`
Dados SSR vazando entre usuários	Mutando estado global	Use contexto para dados com escopo de requisição
Desempenho lento com muitos consumers	Contexto em loops/chamadas frequentes	Obtenha o contexto uma vez no nível superior

Conclusão

As armadilhas do contexto não são bugs aleatórios — são consequências previsíveis de como o JavaScript lida com valores, como o Svelte gerencia a reatividade e como as árvores de componentes estabelecem relacionamentos hierárquicos. Uma vez que você entende esses mecanismos subjacentes, as armadilhas se tornam intuitivas em vez de misteriosas.

A restrição de timing existe porque o contexto é estrutural. O problema de reatribuição existe porque o JavaScript passa referências de objetos, não as variáveis em si. A armadilha da desestruturação existe porque primitivos são copiados por valor. O requisito de posicionamento do provider existe porque o contexto flui para baixo na árvore. Cada armadilha tem uma causa lógica enraizada em comportamentos fundamentais da linguagem e do framework.

As técnicas de depuração neste artigo — inspetores de contexto, rastreamento da pilha de providers, logging estratégico — transformam o contexto de uma caixa preta em um sistema transparente que você pode observar e raciocinar. Quando algo dá errado, você pode identificar sistematicamente se é um problema de timing, de referência, de estrutura de árvore ou de incompatibilidade de chave.

Mais importante, essas armadilhas se tornam cada vez mais raras à medida que você internaliza os padrões. Chame as funções de contexto no nível superior. Mute propriedades, não reatribua objetos. Acesse através do objeto, não desestruture primitivos. Envolva consumers em providers. Use chaves compartilhadas ou Symbols. Siga essas regras de forma consistente, e o contexto se torna uma ferramenta confiável e previsível.

Principais Conclusões

As armadilhas do contexto geralmente se enquadram em algumas categorias:

Problemas de timing — As funções de contexto devem ser chamadas durante a inicialização do componente. Capture os valores cedo, use-os depois.
Problemas de referência — Não reatribua objetos de estado; mute propriedades. Não desestruture primitivos; acesse via objeto.
Problemas de estrutura de árvore — Providers devem ser ancestrais, não irmãos. Componentes dinâmicos precisam ter o contexto encaminhado explicitamente.
Incompatibilidade de chaves — Use constantes compartilhadas, Symbols ou createContext para evitar erros de digitação.
Problemas de reatividade — Use $state para valores reativos. Objetos simples não são rastreados.
Problemas de SSR — Não mute estado global. Use contexto para dados com escopo de requisição.

Ao depurar, use getAllContexts() para ver o que está disponível, adicione logging aos providers e verifique se os providers são ancestrais dos consumers. Com esses padrões reconhecidos, você diagnosticará e corrigirá rapidamente problemas de contexto quando surgirem.

O Que Vem a Seguir

Entenda quando o contexto é a escolha certa em Context vs Other Patterns, comparando contexto com stores, props, eventos e construindo um framework de decisão.

Veja Também

Documentação Oficial

Svelte Context — Guia oficial
createContext — Contexto com tipagem segura

Quando APIs Simples Te Pegam de Surpresa

Armadilha 1: Chamando Funções de Contexto Fora da Inicialização

O Erro

O Que Causa Isso

Exemplos do Erro

A Solução

Por Que Essa Restrição Existe

Armadilha 2: Reatribuindo Objetos de Estado

O Sintoma

O Que Causa Isso

O Erro

Explicação Visual

A Solução

Alternativa: Envolver em Objeto Contêiner

Armadilha 3: Desestruturando Valores Reativos

O Sintoma

O Erro

Por Que Isso Acontece

Soluções

Armadilha 4: Provider Ausente

O Sintoma

O Erro

Soluções

Armadilha 5: Provider na Posição Errada

O Sintoma

O Erro

A Solução

Depuração Visual

Armadilha 6: Chave Errada

O Sintoma

O Erro

Soluções

Armadilha 7: Contexto em Componentes Dinâmicos

O Sintoma

O Erro

A Solução

Armadilha 8: Esperar Reatividade Sem $state

O Sintoma

O Erro

A Solução

Armadilha 9: Usar Contexto para Dados Sensíveis ao SSR

O Sintoma

O Erro

A Solução

Armadilha 10: Contexto em Loops Intensos

O Sintoma

O Erro

A Solução

Padrão Relacionado: Evitar Contexto em Valores Derivados

Técnicas de Depuração

Técnica 1: Componente Inspetor de Contexto

Técnica 2: Console Logging em Providers

Técnica 3: Rastreamento da Pilha de Providers

Técnica 4: Verificando a Posição do Consumer

Técnica 5: Envolvimento com Error Boundary

Referência Rápida: Sintomas e Soluções

Conclusão

Principais Conclusões

O Que Vem a Seguir

Veja Também

Documentação Oficial

Artigos Relacionados