Lendo Context de Ancestrais

No artigo anterior, aprendemos como fornecer context — como transmitir dados de um componente ancestral para que os descendentes possam recebê-los. Agora nos voltamos para o outro lado da equação: consumir context.

Fornecer context é simples: chame setContext com uma chave e um valor, pronto. Consumi-lo tem mais nuances. O que acontece quando o context não existe? Como lidar com context opcional versus obrigatório? E quanto à segurança de tipos? E há uma armadilha sutil de reatividade com desestruturação que pega muitos desenvolvedores de surpresa.

Você não precisa absorver tudo na primeira leitura — concentre-se nos padrões e revisite conforme necessário. Este guia serve tanto como recurso de aprendizado quanto como referência à qual você voltará.

Este artigo cobre tudo o que você precisa para consumir context com confiança:

As três funções de consumidor: getContext, hasContext e getAllContexts
Lidando com context ausente: falha rápida, fallbacks e padrões defensivos
Construindo utilitários reutilizáveis que padronizam o acesso ao context
Consumo com segurança de tipos com createContext e helpers tipados
A armadilha da desestruturação que quebra a reatividade (e como evitá-la)

A Função getContext

A função getContext é sua principal ferramenta para receber valores de context. Vamos examiná-la detalhadamente.

Assinatura da Função

function getContext<T>(key: any): T

A função recebe um único parâmetro, a chave que identifica qual context você deseja, e retorna o valor do context. A chave deve corresponder exatamente ao que foi usado em setContext.

Uso Básico

Em sua forma mais simples:

<script>
	import { getContext } from 'svelte'

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

<p>Welcome, {user.name}!</p>

Se um componente ancestral chamou setContext('user', { name: 'Alice' }), então getContext('user') retorna { name: 'Alice' }.

O Processo de Busca

Quando você chama getContext(key), o Svelte realiza uma busca que percorre a árvore de componentes:

Começa pelo pai do componente atual — O context é definido nos componentes, mas você só pode acessar o context de ancestrais, não de si mesmo.
Verifica cada ancestral — O Svelte verifica se aquele ancestral chamou setContext(key, ...).
Retorna na primeira correspondência — Assim que um ancestral com aquela chave é encontrado, seu valor é retornado.
Retorna undefined se não encontrado — Se nenhum ancestral definiu aquela chave, o valor retornado é undefined e não é um erro, portanto tome cuidado.

Este processo é visualizado abaixo:

App (setContext 'user' → Alice)    ← Step 4: Found! Return Alice
└── Layout                          ← Step 3: No 'user' context
    └── Dashboard                   ← Step 2: No 'user' context
        └── UserBadge               ← Step 1: getContext('user') called here
            Looking for 'user'...

IMPORTANTE: Esta busca acontece apenas uma vez durante a inicialização do componente — o context é estrutural, não reativo por design.

A Regra "O Mais Próximo Vence"

Se múltiplos ancestrais definirem a mesma chave, você obtém o valor do ancestral mais próximo (mais imediato):

RootLayout -> (setContext 'theme' → 'light')
└── Dashboard
    └── AdminPanel -> (setContext 'theme' → 'dark')
        └── Settings
            └── ThemeDisplay  ← getContext('theme') returns 'dark'

ThemeDisplay
↑ SettingsPanel      (no theme)
↑ DashboardLayout    ← FOUND: 'dark'
↑ RootLayout         (ignored)

O componente ThemeDisplay na página Settings recebe 'dark' porque AdminPanel está mais próximo do que RootLayout. Isso permite poderosos padrões de substituição onde componentes internos podem personalizar o context para sua subárvore sem afetar o restante da aplicação.

O que getContext Retorna

O valor de retorno é exatamente o que foi passado para setContext. Sem transformação, sem cópia, sem proxy — apenas o mesmo valor.

Para primitivos (strings, números, booleanos...), você obtém o valor como estava no momento em que setContext foi chamado:

<!-- Provider -->
<script>
	import { setContext } from 'svelte'
	let count = 5
	setContext('count', count)  // Stores 5
	count = 100  // Doesn't affect context
</script>

<!-- Consumer -->
<script>
	import { getContext } from 'svelte'
	const count = getContext('count')  // Gets 5, not 100
</script>

Para objetos (incluindo arrays, funções, instâncias de classe), você obtém uma referência ao mesmo objeto:

<!-- Provider -->
<script>
	import { setContext } from 'svelte'
	const user = { name: 'Alice', score: 0 }
	setContext('user', user)
	// Later...
	user.score = 100  // This IS visible to consumers
</script>

<!-- Consumer -->
<script>
	import { getContext } from 'svelte'
	const user = getContext('user')
	console.log(user.score)  // 100 (sees the modification)
</script>

Este compartilhamento de referência é a base dos padrões de context reativo — mas requer cuidado. Exploraremos isso em profundidade no artigo Tornando o Context Reativo.

Context Ausente Retorna - undefined

Um comportamento crítico: getContext não lança um Error quando a chave não é encontrada. Ele retorna silenciosamente undefined:

<script>
	import { getContext } from 'svelte'

	const user = getContext('user') // undefined if no ancestor set 'user'

	// This would crash!
	console.log(user.name) // TypeError: Cannot read property 'name' of undefined
</script>

Veja o que acontece quando o context está ausente:

┌──────────────────────────────────────────────────────────────────┐
│ Component Initialization                                         │
│                                                                  │
│ const user = getContext('user')  // No provider found            │
│                    ↓                                             │
│           Returns undefined ⚠️  (No error thrown!)               │
│                    ↓                                             │
│ Execution continues normally...                                  │
└──────────────────────────────────────────────────────────────────┘
         │
         ↓ Later, when code tries to use it...
┌──────────────────────────────────────────────────────────────────┐
│ Event Handler / Effect / Render                                  │
│                                                                  │
│ function handleLogin() {                                         │
│   user.login(credentials)  ❌ TypeError: undefined.login         │
│ }                                                                │
│                                                                  │
│ <h1>{user.name}</h1>  ❌ TypeError: undefined.name               │
└──────────────────────────────────────────────────────────────────┘

Problem: Error occurs far from root cause!
         ↓

Three Prevention Strategies:

┌─────────────────────┐   ┌─────────────────────┐   ┌──────────────────────┐
│ 1. FAIL FAST        │   │ 2. FALLBACK         │   │ 3. NULLABLE          │
│                     │   │                     │   │                      │
│ if (!hasContext())  │   │ const user =        │   │ const user =         │
│   throw Error       │   │   hasContext()      │   │   hasContext()       │
│                     │   │   ? getContext()    │   │   ? getContext()     │
│ ✅ Detect at init   │   │   : defaultUser     │   │   : null             │
│ ✅ Clear message    │   │                     │   │                      │
│ ✅ Can't be ignored │   │ ✅ Always usable    │   │ if (user) {          │
│                     │   │ ✅ No crash         │   │   // Has context     │
│ Use: Required       │   │                     │   │ } else {             │
│      context        │   │ Use: Optional       │   │   // No context      │
│                     │   │      enhancement    │   │ }                    │
│                     │   │                     │   │                      │
│                     │   │                     │   │ ✅ Explicit check    │
│                     │   │                     │   │ ✅ Branch logic      │
│                     │   │                     │   │                      │
│                     │   │                     │   │ Use: Conditional     │
│                     │   │                     │   │      features        │
└─────────────────────┘   └─────────────────────┘   └──────────────────────┘

Este comportamento é intencional — permite padrões de context opcional — mas requer tratamento cuidadoso. A próxima seção aborda quando e como usar cada estratégia.

A Restrição de Tempo: Quando getContext Pode Ser Chamado

Assim como setContext, getContext deve ser chamado durante a inicialização do componente — a execução síncrona do seu bloco <script>.

Component Lifecycle Timeline
─────────────────────────────────────────────────────────────────────

Phase 1: INITIALIZATION                Phase 2: REACTIVE RUNTIME
┌─────────────────────────┐           ┌──────────────────────────┐
│ ✅ getContext ALLOWED   │           │ ❌ getContext FORBIDDEN  │
│                         │           │                          │
│ <script>                │           │ • Event handlers         │
│   const x = getContext()│           │ • $effect() callbacks    │
│                         │           │ • setTimeout/Promise     │
│   function setup() {    │           │ • After await            │
│     const y = getContext│           │                          │
│   }                     │           │ function onClick() {     │
│   setup() // ✅ Called  │           │   getContext() // ❌     │
│         immediately     │           │ }                        │
│ </script>               │           │                          │
│                         │           │ $effect(() => {          │
│ All synchronous code    │           │   getContext() // ❌     │
│ in <script> block runs  │           │ })                       │
└─────────────────────────┘           └──────────────────────────┘
         │                                       │
         │ Component mounted                     │ Reactive updates
         ↓                                       ↓
    [Context captured]                    [Use captured values]

Insight importante: Capture referências de context cedo, use-as em todo o código. Se o valor do context contiver propriedades $state, essas permanecem reativas mesmo que a busca em si tenha sido feita apenas uma vez.

Locais Válidos

os seguintes são locais válidos para chamar getContext:

<script>
	import { getContext } from 'svelte'

	// ✅ Top-level in script block
	const theme = getContext('theme')

	// ✅ Inside synchronous function called immediately
	function setupFromContext() {
		const config = getContext('config')
		return config.apiUrl
	}
	const apiUrl = setupFromContext() // Called during initialization

	// ✅ Inside IIFE (Immediately Invoked Function Expression)
	const user = (() => {
		return getContext('user')
	})()

	// ✅ Inside synchronous conditional
	let debug = false
	if (import.meta.env.DEV) {
		const devTools = getContext('devTools')
		debug = devTools?.enabled ?? false
	}
</script>

Locais Inválidos

não chame getContext nestes locais:

<script>
	import { getContext } from 'svelte'

	// ❌ Inside event handler
	function handleClick() {
		const user = getContext('user') // Error!
	}

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

	// ❌ Inside $derived (which runs reactively)
	// Note: $derived runs during initialization, but subsequent runs are reactive
	// This is a subtle edge case—generally avoid getContext in $derived

	// ❌ Inside setTimeout
	setTimeout(() => {
		const config = getContext('config') // Error!
	}, 0)

	// ❌ Inside Promise callbacks
	fetch('/api').then(() => {
		const api = getContext('api') // Error!
	})

	// ❌ After await (which makes the rest async)
	async function setup() {
		const data = await fetch('/api').then((r) => r.json())
		const config = getContext('config') // Error!
	}
	setup()
</script>

A Mensagem de Erro

Se você chamar getContext fora da inicialização, o Svelte lança:

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

Por que Esta Restrição Existe

Esta restrição espelha a que existe em setContext, e por razões relacionadas:

O context é estrutural — Faz parte de como a árvore de componentes é organizada, estabelecida no momento da montagem.
Previsibilidade — Você pode contar com o context estando disponível (ou não) desde o momento em que o componente é inicializado. Ele não vai aparecer ou desaparecer de repente.
Performance — O Svelte não precisa rastrear o acesso ao context de forma reativa; é uma busca única durante a inicialização.

A Solução: Capture Durante a Inicialização

A solução é simples: capture os valores de context durante a inicialização e use-os onde precisar:

<script>
	import { getContext } from 'svelte'

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

	// Now use freely in event handlers
	function handleLogin() {
		auth
			.login(credentials)
			.then(() => {
				toast.success('Welcome back!')
			})
			.catch((err) => {
				toast.error(err.message)
			})
	}

	// And in effects
	$effect(() => {
		document.body.setAttribute('data-theme', theme.current)
	})

	// And in derived values
	let greeting = $derived(`Hello, ${auth.user?.name ?? 'Guest'}!`)
</script>

<button onclick={handleLogin}>Login</button><p>{greeting}</p>

A referência capturada permanece válida durante o ciclo de vida do componente. Se o valor do context for um objeto com propriedades reativas (usando $state), essas propriedades reativas serão atualizadas normalmente.

Verificando Contexto com hasContext

Antes de acessar o contexto, você pode querer verificar se ele existe. A função hasContext faz exatamente isso.

Assinatura da Função

function hasContext(key: any): boolean

Retorna true se algum ancestral definiu esta chave de contexto, false caso contrário.

Uso Básico

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

	// Check before accessing
	if (hasContext('user')) {
		const user = getContext('user')
		console.log('User:', user.name)
	} else {
		console.log('No user context available')
	}
</script>

Padrão Comum: Verificar e Fornecer Valor Padrão

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

	// Get context with fallback
	const theme = hasContext('theme')
		? getContext('theme')
		: { mode: 'light', accentColor: '#007bff' }
</script>

Este padrão é tão comum que você pode querer criar uma função utilitária (faremos isso mais adiante).

Quando Usar hasContext

A decisão de verificar ou não o contexto depende do seu caso de uso:

Cenário	Abordagem	Raciocínio
Contexto é obrigatório	Não verificar; deixar falhar	Contexto obrigatório ausente é um bug; falhe rápido e de forma evidente
Contexto é opcional com valor padrão sensato	Verificar com `hasContext`, fornecer padrão	O componente deve funcionar de forma independente
Comportamento diferente com/sem contexto	Verificar e ramificar	Alguns recursos só estão disponíveis em determinados contextos
Componente de biblioteca/reutilizável	Geralmente verificar	Componentes podem ser usados fora dos provedores esperados
Componente interno de aplicação	Frequentemente não verificar	Você controla o ambiente

hasContext Não Consome o Contexto

Um detalhe importante: hasContext apenas verifica a existência — ele não recupera nem "consome" o contexto. Você pode chamá-lo várias vezes sem efeitos colaterais:

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

	// These are independent checks
	const hasTheme = hasContext('theme')
	const hasUser = hasContext('user')
	const hasFeatureFlags = hasContext('features')

	// Now conditionally get what we need
	const theme = hasTheme ? getContext('theme') : defaultTheme
	const user = hasUser ? getContext('user') : null
</script>

Inspecionando Todo o Contexto com getAllContexts

A função getAllContexts retorna o mapa de contexto completo disponível na posição atual na árvore.

Assinatura da Função

function getAllContexts<T extends Map<any, any> = Map<any, any>>(): T

Retorna um Map JavaScript contendo todos os pares chave-valor de contexto acessíveis a este componente.

Uso Básico

<script>
	import { getAllContexts } from 'svelte'

	const allContexts = getAllContexts()

	console.log(allContexts)
	// Map(3) {
	//   'theme' => { mode: 'dark', ... },
	//   'user' => { name: 'Alice', ... },
	//   Symbol('auth') => { ... }
	// }

	// Use Map methods
	console.log(allContexts.has('theme')) // true
	console.log(allContexts.get('user')) // { name: 'Alice', ... }
	console.log(allContexts.size) // 3
</script>

1: Depuração

Quando algo não está funcionando, é útil ver qual contexto está realmente disponível:

<script>
	import { getAllContexts } from 'svelte'

	// Development-only context inspection
	if (import.meta.env.DEV) {
		const ctx = getAllContexts()
		console.group('🔍 Available Context')
		for (const [key, value] of ctx) {
			console.log(`${String(key)}:`, value)
		}
		console.groupEnd()
	}
</script>

Você pode criar um componente de depuração reutilizável:

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

	let { show = false } = $props()

	const allContexts = getAllContexts()
	const entries = [...allContexts.entries()]
</script>

{#if show && import.meta.env.DEV}
	<details class="context-debugger">
		<summary>Context ({entries.length} keys)</summary>
		<ul>
			{#each entries as [key, value]}
				<li>
					<strong>{String(key)}</strong>
					<pre>{JSON.stringify(value, null, 2)}</pre>
				</li>
			{/each}
		</ul>
	</details>
{/if}

<style>
	.context-debugger {
		position: fixed;
		bottom: 1rem;
		right: 1rem;
		background: #1e1e1e;
		color: #d4d4d4;
		padding: 0.5rem;
		border-radius: 4px;
		font-size: 12px;
		max-width: 400px;
		max-height: 300px;
		overflow: auto;
		z-index: 9999;
	}

	pre {
		margin: 0;
		white-space: pre-wrap;
		word-break: break-all;
	}
</style>

2: Encaminhando Contexto para Componentes Dinâmicos

Quando você monta dinamicamente um componente fora da árvore normal (por exemplo, um modal renderizado em um portal), pode querer que ele herde o contexto atual:

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

	// Capture context that should be forwarded
	const inheritedContext = getAllContexts()

	let modalInstance = null

	function openModal(content) {
		// Mount modal at document.body but with inherited context
		modalInstance = mount(Modal, {
			target: document.body,
			props: { content },
			context: inheritedContext // Forward context!
		})
	}

	function closeModal() {
		if (modalInstance) {
			modalInstance.$destroy()
			modalInstance = null
		}
	}
</script>

Sem o encaminhamento de contexto, o modal não teria nenhum contexto (já que document.body não possui nenhum ancestral Svelte com contexto).

3: Criando Wrappers que Encaminham Contexto

Às vezes você precisa envolver um componente preservando todo o seu acesso ao contexto:

<!-- ContextPreservingWrapper.svelte -->
<script>
	import { getAllContexts, setContext } from 'svelte'

	let { children, additionalContext = {} } = $props()

	// Get all inherited context
	const inherited = getAllContexts()

	// Re-provide everything from ancestors
	for (const [key, value] of inherited) {
		setContext(key, value)
	}

	// Add any additional context
	for (const [key, value] of Object.entries(additionalContext)) {
		setContext(key, value)
	}
</script>

<div class="wrapper">
	{@render children()}
</div>

Nota sobre Timing

Como as outras funções de contexto, getAllContexts deve ser chamado durante a inicialização do componente.

Lidando com Contexto Ausente: Estratégias e Padrões

Contexto ausente é uma das fontes mais comuns de erros em tempo de execução em arquiteturas baseadas em contexto. Um componente espera que getContext('user') retorne um objeto de usuário, mas obtém undefined — e de repente você está depurando um enigmático erro "Cannot read property 'name' of undefined" três componentes afastado do problema real.

A percepção fundamental é que situações diferentes exigem estratégias diferentes. Às vezes, contexto ausente é um bug que deve falhar de forma evidente. Outras vezes é esperado e seu componente deve degradar graciosamente. Vamos explorar quando usar cada abordagem.

Estratégia 1: Falhar Rapidamente para Contexto Obrigatório

Quando o contexto é genuinamente obrigatório — ou seja, seu componente não pode funcionar sem ele — a melhor abordagem é falhar imediatamente com uma mensagem de erro clara e acionável:

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

	if (!hasContext('auth')) {
		throw new Error(
			'AuthContext not found. ' +
				'Wrap this component in a layout that provides auth context. ' +
				'See: src/routes/+layout.svelte'
		)
	}

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

Por que falhar rapidamente?

Feedback imediato: Você descobre o problema durante o desenvolvimento, não em produção quando um usuário clica em um botão
Diagnóstico claro: A mensagem de erro diz aos desenvolvedores exatamente o que está errado e onde procurar
Previne falhas em cascata: Sem essa verificação, você obteria um erro confuso como TypeError: Cannot read property 'login' of undefined em algum lugar dentro de um manipulador de eventos

Use essa estratégia para contextos que são requisitos arquiteturais — coisas como autenticação, roteamento ou configuração global da aplicação.

Estratégia 2: Fallback Gracioso para Contexto Opcional

Alguns contextos aprimoram um componente, mas não são essenciais. Um componente Button pode ficar melhor quando respeita o contexto de tema, mas ainda deve renderizar um botão perfeitamente funcional sem ele:

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

	let { children, onclick } = $props()

	// Theme is optional—component works without it
	const defaultTheme = {
		primaryColor: '#007bff',
		borderRadius: '4px'
	}

	const theme = hasContext('theme') ? getContext('theme') : defaultTheme
</script>

<button
	{onclick}
	style="
		background: {theme.primaryColor};
		border-radius: {theme.borderRadius};
	"
>
	{@render children()}
</button>

Este padrão torna os componentes portáteis. Você pode usá-los em qualquer projeto — independentemente de ter ou não seu sistema de temas — e eles simplesmente funcionam.

Estratégia 3: Null Explícito para Recursos Condicionais

Às vezes você precisa saber se o contexto foi fornecido em vez de usar um valor padrão. Por exemplo, você pode exibir interfaces diferentes para usuários autenticados versus anônimos:

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

	// Explicitly null when not available (not a default user object)
	const user = hasContext('user') ? getContext('user') : null
</script>

{#if user}
	<nav>
		<span>Welcome, {user.name}</span>
		<a href="/dashboard">Dashboard</a>
		<button onclick={() => auth.logout()}>Logout</button>
	</nav>
{:else}
	<nav>
		<a href="/login">Sign In</a>
		<a href="/register">Create Account</a>
	</nav>
{/if}

Usar null (em vez de um usuário padrão fictício) torna a distinção cristalina no seu código.

Estratégia 4: Optional Chaining para Acesso Rápido

Para casos simples onde você só precisa de acesso seguro a propriedades, o optional chaining é conciso:

<script>
	import { getContext } from 'svelte'

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

<!-- Safe even if user is undefined -->
<p>Hello, {user?.name ?? 'Guest'}!</p>

<!-- Conditionally call methods -->
<button onclick={() => analytics?.track('button_clicked')}> Click me </button>

Isso funciona bem para componentes folha que consomem contexto passivamente. No entanto, evite usar em excesso—se você se encontrar escrevendo user?. em todo lugar, considere usar a Estratégia 2 ou 3 no topo do seu script.

Escolhendo a Estratégia Certa

Cenário	Estratégia	Por quê
Componente não pode funcionar sem contexto	Fail Fast	Captura erros de configuração imediatamente
Contexto melhora, mas não é obrigatório	Graceful Fallback	Componente permanece portátil
UI diferente para "tem contexto" vs "não tem"	Explicit Null	Lógica condicional clara
Acesso pontual a propriedade	Optional Chaining	Conciso para casos simples
Biblioteca/componente reutilizável	Graceful Fallback	Funciona em qualquer ambiente
Componente interno com provider garantido	Fail Fast	Documenta o requisito

Construindo Utilitários de Contexto Reutilizáveis

Se você se encontrar repetindo os mesmos padrões de manipulação de contexto em muitos componentes, é hora de extraí-los em utilitários. Isso não só reduz o boilerplate como também padroniza a forma como sua equipe lida com contexto em toda a aplicação.

Um Módulo de Utilitários Prático

Aqui está um conjunto de utilitários que cobre os padrões mais comuns:

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

/**
 * Gets context or returns a fallback value.
 * Use for optional context with sensible defaults.
 *
 * @example
 * const theme = getContextOr('theme', { mode: 'light' })
 */
export function getContextOr<T>(key: any, fallback: T): T {
	return hasContext(key) ? getContext(key) : fallback
}

/**
 * Gets context or returns null.
 * Use when you need to distinguish "no context" from "has context".
 *
 * @example
 * const user = getContextOrNull('user')
 * if (user) { ... }
 */
export function getContextOrNull<T>(key: any): T | null {
	return hasContext(key) ? getContext(key) : null
}

/**
 * Gets context or throws a descriptive error.
 * Use for required context that must be provided by an ancestor.
 *
 * @example
 * const auth = requireContext('auth', 'Authentication')
 */
export function requireContext<T>(key: any, contextName: string): T {
	if (!hasContext(key)) {
		throw new Error(
			`${contextName} context is required but was not found. ` +
				`Ensure this component is rendered within a provider that sets '${String(key)}' context.`
		)
	}
	return getContext(key)
}

Usando os Utilitários

Com esses utilitários, seus componentes ficam mais limpos e consistentes:

<script>
	import { requireContext, getContextOr, getContextOrNull } from '$lib/context/utils'

	// Required: throws descriptive error if missing
	const auth = requireContext('auth', 'Authentication')

	// Optional with default: always returns a usable value
	const theme = getContextOr('theme', { mode: 'light', accent: '#007bff' })

	// Optional nullable: returns null if missing
	const analytics = getContextOrNull('analytics')

	function trackClick() {
		// Only track if analytics is available
		analytics?.track('button_clicked')
	}
</script>

Criando Acessores de Contexto Tipados

Para uma experiência de desenvolvimento ainda melhor, crie acessores tipados para cada contexto na sua aplicação:

// src/lib/context/auth.ts
import { getContext, hasContext, setContext } from 'svelte'

export interface AuthContext {
	readonly user: User | null
	readonly isAuthenticated: boolean
	login(credentials: Credentials): Promise<void>
	logout(): Promise<void>
}

const AUTH_KEY = Symbol('auth')

export function setAuthContext(value: AuthContext) {
	return setContext(AUTH_KEY, value)
}

export function getAuthContext(): AuthContext {
	if (!hasContext(AUTH_KEY)) {
		throw new Error(
			'Auth context not found. ' +
				'Ensure this component is rendered within src/routes/+layout.svelte'
		)
	}
	return getContext(AUTH_KEY)
}

export function getAuthContextOrNull(): AuthContext | null {
	return hasContext(AUTH_KEY) ? getContext(AUTH_KEY) : null
}

Agora consumir o contexto de autenticação é totalmente tipado e autodocumentado:

<script lang="ts">
	import { getAuthContext } from '$lib/context/auth'

	const auth = getAuthContext()

	// Full TypeScript support
	auth.user?.name // ✅ string | undefined
	auth.isAuthenticated // ✅ boolean
	auth.login(creds) // ✅ Promise<void>
</script>

Esse padrão escala bem—crie um arquivo por domínio de contexto (auth.ts, theme.ts, toast.ts) e sua equipe sempre saberá exatamente como fornecer e consumir cada contexto.

Consumo com Type Safety

A integração com TypeScript torna o consumo de contexto mais seguro e ergonômico.

Asserções de Tipo Básicas

Com getContext puro, você precisa declarar os tipos:

<script lang="ts">
	import { getContext } from 'svelte'

	interface User {
		id: string
		name: string
		email: string
	}

	// Type assertion needed
	const user = getContext('user') as User

	// Or with generic
	const user2 = getContext<User>('user')
</script>

Isso funciona, mas tem desvantagens:

A asserção pode estar errada (sem verificação em tempo de execução)
Você precisa importar/definir o tipo em todo lugar que consumir

Usando `createContext` (Recomendado)

Com createContext (Svelte 5.40+), os tipos são inferidos automaticamente:

// lib/context/user.ts
import { createContext } from 'svelte'

export interface User {
	id: string
	name: string
	email: string
	role: 'admin' | 'user' | 'guest'
}

export const [getUser, setUser] = createContext<User>()

<!-- Consumer.svelte -->
<script lang="ts">
	import { getUser } from '$lib/context/user'

	// Fully typed! No assertion needed.
	const user = getUser()

	// TypeScript knows everything
	user.name // ✅ string
	user.email // ✅ string
	user.role // ✅ 'admin' | 'user' | 'guest'
	user.foo // ❌ Property 'foo' does not exist
</script>

`createContext` Lança Erro quando Ausente

Ao contrário de getContext, o getter de createContext lança quando o contexto está ausente:

<script>
	import { getUser } from '$lib/context/user'

	// If no ancestor called setUser(), this throws immediately:
	// "Context was not provided"
	const user = getUser()
</script>

Isso é uma funcionalidade, não um bug—ele captura erros de configuração durante o desenvolvimento em vez de causar erros misteriosos de undefined mais tarde.

`createContext` com Valores Padrão

Você pode fornecer um valor padrão que é usado quando nenhum provider define o contexto:

// lib/context/config.ts
import { createContext } from 'svelte'

interface Config {
	apiUrl: string
	timeout: number
	debug: boolean
}

export const [getConfig, setConfig] = createContext<Config>({
	apiUrl: '/api',
	timeout: 5000,
	debug: false
})

Agora getConfig() retorna o padrão se nenhum ancestral forneceu o config, em vez de lançar um erro.

Consumindo Múltiplos Contextos

Componentes do mundo real frequentemente precisam de dados de vários contextos—configurações de tema, informações do usuário, feature flags, notificações toast. Vamos explorar padrões para gerenciar isso de forma limpa.

Abordagem Direta: Múltiplas Chamadas a getContext

A abordagem direta funciona bem para a maioria dos componentes:

<script>
	import { getContext } from 'svelte'

	const theme = getContext('theme')
	const user = getContext('user')
	const locale = getContext('locale')
	const toast = getContext('toast')
</script>

Isso é explícito, fácil de entender e funciona perfeitamente para componentes que precisam de alguns contextos. Não complique demais.

Hook Consolidado para Conjuntos Comuns de Contexto

Se muitos componentes precisam da mesma combinação de contextos, extraia um hook:

// src/lib/hooks/useAppContext.ts
import { getContext, hasContext } from 'svelte'

export function useAppContext() {
	return {
		user: getContext('user'),
		theme: hasContext('theme') ? getContext('theme') : { mode: 'light' },
		locale: getContext('locale'),
		toast: getContext('toast')
	}
}

<script>
	import { useAppContext } from '$lib/hooks/useAppContext'

	const { user, theme, locale, toast } = useAppContext()
</script>

Lembre-se: Esta função deve ser chamada durante a inicialização do componente—você não pode chamá-la dentro de um event handler.

Hooks por Domínio (Recomendado para Aplicações Grandes)

Em vez de um hook monolítico, crie hooks focados para cada domínio:

// src/lib/hooks/useAuth.ts
import { requireContext } from '$lib/context/utils'

export function useAuth() {
	return requireContext('auth', 'Authentication')
}

// src/lib/hooks/useTheme.ts
import { getContextOr } from '$lib/context/utils'

const defaultTheme = { mode: 'light', accent: '#007bff' }

export function useTheme() {
	return getContextOr('theme', defaultTheme)
}

// src/lib/hooks/usePermissions.ts
import { getContextOr } from '$lib/context/utils'

export function usePermissions() {
	const permissions = getContextOr('permissions', [])

	return {
		list: permissions,
		has: (perm: string) => permissions.includes(perm),
		hasAll: (...perms: string[]) => perms.every((p) => permissions.includes(p)),
		hasAny: (...perms: string[]) => perms.some((p) => permissions.includes(p))
	}
}

O uso é limpo e autodocumentado:

<script>
	import { useAuth } from '$lib/hooks/useAuth'
	import { useTheme } from '$lib/hooks/useTheme'
	import { usePermissions } from '$lib/hooks/usePermissions'

	const auth = useAuth()
	const theme = useTheme()
	const { has: hasPermission } = usePermissions()
</script>

{#if hasPermission('admin')}
	<AdminPanel />
{/if}

Este padrão escala bem porque cada hook:

Encapsula seu próprio tratamento de erros
Fornece padrões sensatos
Pode adicionar propriedades computadas (como hasPermission)
É testável de forma independente

A Armadilha da Desestruturação: Um Problema Comum de Reatividade

Existe um problema sutil, mas importante, ao trabalhar com contexto reativo que pega muitos desenvolvedores de surpresa. Entendê-lo vai te poupar horas de depuração.

O Problema: Reatividade Perdida

Considere este código de aparência inocente:

<script>
	import { getContext } from 'svelte'

	const settings = getContext('settings')
	// settings = { theme: 'light', fontSize: 16, language: 'en' }

	// Destructuring seems convenient...
	const { theme, fontSize, language } = settings
</script>

<div class={theme}>
	<p style="font-size: {fontSize}px">Language: {language}</p>
</div>

Agora imagine que o provedor atualiza settings.theme para 'dark'. Seu componente não vai atualizar. Ele ainda mostra 'light'.

Por Que Isso Acontece

Quando você desestrutura, o JavaScript extrai os valores naquele momento e os atribui a novas variáveis:

const { theme } = settings
// Is equivalent to:
const theme = settings.theme // Copies 'light' into a new variable

A variável theme agora contém a string 'light' de forma independente. Não há conexão contínua com themeSettings.theme. Quando o provedor muda themeSettings.theme para 'dark', sua variável theme não é afetada—ela ainda é 'light'.

Solução 1: Acessar Propriedades Diretamente (Mais Simples)

A correção mais fácil é ignorar a desestruturação e acessar as propriedades diretamente no objeto:

<script>
	import { getContext } from 'svelte'

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

<!-- Access properties directly—this WILL update -->
<div class={settings.theme}>
	<p style="font-size: {settings.fontSize}px">
		Language: {settings.language}
	</p>
</div>

Cada vez que o Svelte renderiza, ele lê o valor atual de settings.theme. Se o provedor o alterou, você verá o novo valor.

Solução 2: Desestruturação Reativa com `$derived`

Se você quiser a conveniência de nomes de variáveis curtos, use $derived para criar vínculos reativos:

<script>
	import { getContext } from 'svelte'

	const settings = getContext('settings')

	// These re-evaluate whenever settings changes
	let theme = $derived(settings.theme)
	let fontSize = $derived(settings.fontSize)
	let language = $derived(settings.language)
</script>

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

Cada $derived cria um vínculo reativo que é recalculado sempre que suas dependências mudam.

Solução 3: Desestruturação no Template com `{@const}`

Para uso pontual em um bloco de template específico, você pode desestruturar exatamente onde precisar:

<script>
	import { getContext } from 'svelte'

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

{@const { theme, fontSize, language } = settings}
<div class={theme}>
	<p style="font-size: {fontSize}px">Language: {language}</p>
</div>

A declaração {@const} é executada a cada renderização, então sempre captura os valores atuais. Isso é útil quando você precisa de desestruturação dentro de um loop ou bloco condicional.

Quando Isso Importa?

Essa armadilha só afeta você quando:

O valor do contexto é reativo (contém $state internamente)
Você desestrutura valores primitivos (strings, números, booleanos)
O provedor realmente muda esses valores

Se seu contexto é uma configuração somente leitura que nunca muda, a desestruturação é perfeitamente válida. Mas na dúvida, acesse as propriedades diretamente—isso é sempre seguro.

Exploraremos padrões de reatividade com muito mais profundidade no artigo Tornando o Contexto Reativo.

Juntando Tudo: Um Exemplo do Mundo Real

Vamos aplicar tudo o que aprendemos para construir um componente Card que demonstra padrões robustos de consumo de contexto.

Os Requisitos

Nosso componente Card deve:

Adaptar-se ao contexto de tema quando disponível
Funcionar de forma independente com padrões sensatos (portabilidade)
Suportar variantes que derivam cores do tema
Ser totalmente tipado para uma ótima experiência de desenvolvimento

A Implementação

<!-- src/lib/components/Card.svelte -->
<script lang="ts">
	import { getContext, hasContext } from 'svelte'

	// --- Props ---
	interface Props {
		title?: string
		subtitle?: string
		variant?: 'default' | 'primary' | 'muted'
		children: import('svelte').Snippet
	}

	let { title, subtitle, variant = 'default', children }: Props = $props()

	// --- Theme Context (optional with fallback) ---
	interface Theme {
		mode: 'light' | 'dark'
		colors: {
			primary: string
			background: string
			text: string
			muted: string
			border: string
		}
		borderRadius: string
		shadow: string
	}

	const defaultTheme: Theme = {
		mode: 'light',
		colors: {
			primary: '#007bff',
			background: '#ffffff',
			text: '#1a1a1a',
			muted: '#f5f5f5',
			border: '#e0e0e0'
		},
		borderRadius: '8px',
		shadow: '0 2px 8px rgba(0, 0, 0, 0.1)'
	}

	// Strategy 2: Graceful fallback for optional context
	const theme: Theme = hasContext('theme') ? getContext('theme') : defaultTheme

	// --- Derived Styling ---
	// Use $derived to react to theme changes
	let backgroundColor = $derived(
		{
			default: theme.colors.background,
			primary: theme.colors.primary,
			muted: theme.colors.muted
		}[variant]
	)

	let textColor = $derived(variant === 'primary' ? '#ffffff' : theme.colors.text)
</script>

<article
	class="card"
	class:dark={theme.mode === 'dark'}
	style="
		--card-bg: {backgroundColor};
		--card-text: {textColor};
		--card-border: {theme.colors.border};
		--card-radius: {theme.borderRadius};
		--card-shadow: {theme.shadow};
	"
>
	{#if title}
		<header class="card-header">
			<h3 class="card-title">{title}</h3>
			{#if subtitle}
				<p class="card-subtitle">{subtitle}</p>
			{/if}
		</header>
	{/if}

	<div class="card-body">
		{@render children()}
	</div>
</article>

<style>
	.card {
		background: var(--card-bg);
		color: var(--card-text);
		border: 1px solid var(--card-border);
		border-radius: var(--card-radius);
		box-shadow: var(--card-shadow);
		overflow: hidden;
	}

	.card.dark {
		border-color: rgba(255, 255, 255, 0.1);
	}

	.card-header {
		padding: 1rem 1.5rem;
		border-bottom: 1px solid var(--card-border);
	}

	.card-title {
		margin: 0;
		font-size: 1.25rem;
		font-weight: 600;
	}

	.card-subtitle {
		margin: 0.25rem 0 0;
		opacity: 0.7;
		font-size: 0.875rem;
	}

	.card-body {
		padding: 1.5rem;
	}
</style>

O Que Torna Isso Robusto

Funciona em qualquer lugar: O tema padrão garante que o card seja renderizado de forma bonita mesmo sem um provedor de tema
Adapta-se quando o contexto existe: Quando usado dentro de um layout com tema, ele automaticamente adota as cores e o estilo do aplicativo
Reativo a mudanças: Usar $derived para cores de variantes significa que o card é atualizado se o tema alternar entre os modos claro/escuro
Totalmente tipado: O TypeScript detecta incompatibilidades entre as estruturas de tema esperadas e fornecidas
Propriedades customizadas de CSS: A ponte entre script e estilos mantém o componente sustentável

Exemplos de Uso

<!-- Works standalone -->
<div class="grid">
	<!-- Works standalone -->
	<Card title="Hello World">
		<p>This card uses default styling.</p>
	</Card>

	<!-- Adapts to theme context -->
	<Card title="Themed Card" variant="primary">
		<p>This card uses your app's primary color.</p>
	</Card>

	<!-- Inside a dark-themed section -->
	<Card title="Dark Mode" subtitle="Automatically adapts">
		<p>Border and shadow adjust for dark backgrounds.</p>
	</Card>
</div>

<style>
	.grid {
		display: grid;
		gap: 1.5rem;
		grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
		margin-top: 2rem;
	}
</style>

Conclusão

Consumir contexto é o contraponto de fornecê-lo, e entender ambos os lados completa seu modelo mental de como os dados fluem pela árvore de componentes do Svelte. Enquanto fornecer contexto é sobre anunciar disponibilidade, consumir contexto é sobre acessar essa disponibilidade de forma confiável e segura.

Os padrões neste artigo—desde chamadas básicas de getContext até utilitários tipados sofisticados—todos abordam o mesmo desafio fundamental: como acessar dados que podem ou não existir, de uma forma que seja segura em termos de tipos, sustentável e depurável? A resposta depende do seu caso de uso: falha rápida para contexto obrigatório, fallbacks elegantes para contexto opcional, e verificações de null explícitas quando você precisa distinguir entre os dois.

A armadilha da desestruturação merece ênfase especial porque pega tantos desenvolvedores desprevenidos. O modelo mental a lembrar é simples: primitivos são copiados, referências são compartilhadas. Quando você desestrutura um primitivo de um objeto de contexto reativo, você obtém um instantâneo que nunca atualiza. Quando você o acessa através do objeto (context.theme em vez de apenas theme), você obtém o valor atual toda vez.

Com o fornecimento e o consumo de contexto dominados, você está equipado para construir aplicações onde os dados fluem de forma limpa pela sua árvore de componentes—sem prop drilling, sem acoplamento através de intermediários, apenas declarações claras do que está disponível e do que é necessário.

Principais Conclusões

Consumir contexto de forma eficaz se resume a entender alguns princípios-chave:

As Funções Principais

getContext(key) recupera o contexto do ancestral mais próximo. Retorna undefined se não encontrado—não um erro.
hasContext(key) verifica a existência sem recuperar. Use isso para padrões de contexto opcional.
getAllContexts() retorna tudo como um Map. Ótimo para depuração e encaminhamento de contexto.

A Regra de Temporização

Todas as funções de contexto devem ser executadas durante a inicialização do componente. Capture o que você precisa no topo do seu script e use esses valores em qualquer lugar.

Lidando com Contexto Ausente

Situação	Estratégia
O componente não consegue funcionar sem ele	Falha rápida com erro descritivo
Melhoria opcional	Fornecer padrão sensato
Necessidade de distinguir "ausente" de "presente"	Retornar null explícito
Acesso rápido e pontual	Encadeamento opcional (`context?.value`)

A Armadilha da Desestruturação

A desestruturação quebra a reatividade para valores primitivos. Acesse as propriedades diretamente no objeto de contexto, ou use $derived para criar vínculos reativos.

Segurança de Tipos

Use createContext (Svelte 5.40+) para tipagem automática e comportamento de erro-em-caso-de-ausência, ou crie funções utilitárias tipadas para padronizar o acesso ao contexto em todo o seu aplicativo.

Com esses padrões dominados, você consumirá contexto de forma segura e eficaz em seus aplicativos Svelte.

O Que Vem a Seguir

Explore como o contexto se comporta em hierarquias de componentes complexas em Escopo e Fluxo de Contexto, onde você dominará a regra "o mais próximo vence" e os padrões de substituição de contexto.

Veja Também

Documentação Oficial

API getContext — Referência da API
API hasContext — Referência da API
API getAllContexts — Referência da API

Lendo Context de Ancestrais

A Função getContext

Assinatura da Função

Uso Básico

O Processo de Busca

A Regra "O Mais Próximo Vence"

O que getContext Retorna

Context Ausente Retorna - undefined

A Restrição de Tempo: Quando getContext Pode Ser Chamado

Locais Válidos

Locais Inválidos

A Mensagem de Erro

Por que Esta Restrição Existe

A Solução: Capture Durante a Inicialização

Verificando Contexto com hasContext

Assinatura da Função

Uso Básico

Padrão Comum: Verificar e Fornecer Valor Padrão

Quando Usar hasContext

hasContext Não Consome o Contexto

Inspecionando Todo o Contexto com getAllContexts

Assinatura da Função

Uso Básico

1: Depuração

2: Encaminhando Contexto para Componentes Dinâmicos

3: Criando Wrappers que Encaminham Contexto

Nota sobre Timing

Lidando com Contexto Ausente: Estratégias e Padrões

Estratégia 1: Falhar Rapidamente para Contexto Obrigatório

Estratégia 2: Fallback Gracioso para Contexto Opcional

Estratégia 3: Null Explícito para Recursos Condicionais

Estratégia 4: Optional Chaining para Acesso Rápido

Escolhendo a Estratégia Certa

Construindo Utilitários de Contexto Reutilizáveis

Um Módulo de Utilitários Prático

Usando os Utilitários

Criando Acessores de Contexto Tipados

Consumo com Type Safety

Asserções de Tipo Básicas

Usando createContext (Recomendado)

createContext Lança Erro quando Ausente

createContext com Valores Padrão

Consumindo Múltiplos Contextos

Abordagem Direta: Múltiplas Chamadas a getContext

Hook Consolidado para Conjuntos Comuns de Contexto

Hooks por Domínio (Recomendado para Aplicações Grandes)

A Armadilha da Desestruturação: Um Problema Comum de Reatividade

O Problema: Reatividade Perdida

Por Que Isso Acontece

Solução 1: Acessar Propriedades Diretamente (Mais Simples)

Solução 2: Desestruturação Reativa com $derived

Solução 3: Desestruturação no Template com {@const}

Quando Isso Importa?

Juntando Tudo: Um Exemplo do Mundo Real

Os Requisitos

A Implementação

O Que Torna Isso Robusto

Exemplos de Uso

Conclusão

Principais Conclusões

O Que Vem a Seguir

Veja Também

Documentação Oficial

Artigos Relacionados

Usando `createContext` (Recomendado)

`createContext` Lança Erro quando Ausente

`createContext` com Valores Padrão

Solução 2: Desestruturação Reativa com `$derived`

Solução 3: Desestruturação no Template com `{@const}`