O Obstáculo que Todo Desenvolvedor Svelte Encontra

Todo desenvolvedor Svelte eventualmente encontra um obstáculo. Você tem dados em um componente — talvez informações do usuário, configurações de tema ou configuração da aplicação — e precisa desses mesmos dados em outro componente enterrado profundamente na sua árvore de componentes. A solução direta de passar os dados como props por cada componente intermediário tecnicamente funciona, mas algo parece fundamentalmente errado nisso. Você está escrevendo código repetitivo que não serve a outro propósito além de encaminhar dados por componentes que nem sequer se importam com eles.

Esse padrão frustrante tem um nome no mundo do desenvolvimento frontend: prop drilling. E a API de Contexto do Svelte existe especificamente para resolvê-lo.

Contexto em 60 Segundos

A API de Contexto faz uma coisa: permite que um componente pai transmita dados que qualquer descendente pode receber diretamente, independentemente de quão profundamente aninhado esteja.

O componente A define um valor de contexto. Cada descendente (B, C, D, E, F, G) pode acessá-lo diretamente com getContext().

Quando os componentes intermediários (B e C) não precisam saber que os dados existem — eles não recebem props e não encaminham nada. D e G podem simplesmente acessar e pegar o que precisam usando getContext().

Veja como isso fica no código:

<!-- Provider.svelte (Component A) -->
<script>
	import { setContext } from 'svelte'
	import Intermediate from './Intermediate.svelte'

	setContext('user', { name: 'Alice', role: 'admin' })
</script>

<Intermediate />

<!-- Intermediate.svelte (Component B) -->
<script>
	import Consumer from './Consumer.svelte'
	// No props! This component doesn't know about 'user'
</script>

<Consumer />

<!-- Consumer.svelte (Component D) -->
<script>
	import { getContext } from 'svelte'

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

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

Esse é o conceito inteiro: defina uma vez, acesse em qualquer lugar abaixo.

Terminologia

Ao longo desta série, utilizamos uma nomenclatura consistente:

Termo	Significado
Provider	Um componente que chama `setContext()` para transmitir dados
Consumer	Um componente que chama `getContext()` para receber dados
Intermediário	Um componente entre provider e consumer que não utiliza o contexto

Prop Drilling

O problema que a API de Contexto resolve é o prop drilling, que significa que os dados devem ser passados por cada componente na cadeia. Vejamos um exemplo sem contexto:

<!-- Provider.svelte -->
<script>
	import Intermediate from './Intermediate.svelte'
	const user = { name: 'Alice', email: 'alice@example.com' }
</script>

<Intermediate {user} />

<!-- Intermediate.svelte -->
<script>
	import Consumer from './Consumer.svelte'
	let { user } = $props() // Intermediate doesn't use this!
</script>

<Consumer {user} />

<!-- Consumer.svelte -->
<script>
	let { user } = $props()
</script>

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

Isso é prop drilling: passar dados por componentes que não os utilizam.

Por que Isso é Problemático

Ruído no código: Intermediate tem uma prop user que nunca usa
Acoplamento desnecessário: Intermediate agora está acoplado ao conceito de "usuário"
Custo de refatoração: Adicionar user.email ao Consumer exige verificar cada componente na cadeia
Dificuldade nos testes: Testar Intermediate requer simular user mesmo que ele não o utilize

Em aplicações reais com 6 ou mais níveis de aninhamento, esse problema se multiplica significativamente.

Modelos Mentais

Para entender melhor como o contexto funciona, aqui estão duas formas de pensar sobre contexto que ajudam a prever seu comportamento.

Transmissão de Rádio

Conceito	Rádio	Contexto Svelte
Transmissor	Estação de rádio	`setContext()`
Frequência	98,7 FM	Chave de contexto
Conteúdo	Programa/música	Valor de contexto
Ouvinte	Receptor de rádio	`getContext()`
Cobertura	Alcance do transmissor	Componentes descendentes

Comportamentos principais:

Sentido único — Transmite para baixo, nunca para cima
Somente descendentes — Irmãos e pais não podem receber
O mais próximo vence — Se dois ancestrais definem a mesma chave, você obtém o mais próximo
Escutar é opcional — Componentes podem ignorar contextos que não precisam

Mural de Avisos

Imagine um prédio de escritórios onde cada andar tem um mural de avisos:

Quando você precisa de uma informação, verifique o mural do seu andar
Se não estiver lá, suba um andar e verifique novamente
Continue subindo até encontrar (ou chegar ao topo sem encontrar nada)
Cada andar pode publicar sua própria versão, substituindo o que está acima

Isso enfatiza o processo de busca: getContext() percorre a árvore para cima até encontrar uma correspondência.

As Funções Principais

A API de Contexto do Svelte fornece quatro funções de contexto:

Função	Propósito
`setContext(key, value)`	Transmite um valor para os descendentes
`getContext(key)`	Recebe um valor de um ancestral
`hasContext(key)`	Verifica se o contexto existe (retorna booleano)
`getAllContexts()`	Obtém todo o contexto como um Map (para depuração/encaminhamento)

Regra fundamental: Todas as quatro devem ser chamadas durante a inicialização do componente — a execução síncrona do seu bloco <script>. Você não pode chamá-las em manipuladores de eventos, efeitos ou após um await.

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

	// VALID - during initialization
	setContext('config', { debug: true })
	const user = getContext('user')

	// INVALID - after initialization
	function handleClick() {
		setContext('late', 'value') // Error!
	}
</script>

Por quê? O contexto faz parte da estrutura da árvore de componentes, estabelecida quando os componentes são montados. No momento em que os manipuladores são executados, os descendentes já tentaram ler o contexto.

Para uma cobertura detalhada de cada função, consulte Fornecendo Contexto e Consumindo Contexto.

Quando Usar Contexto

O contexto é poderoso, mas nem sempre é a ferramenta certa. Aqui está um guia de decisão:

Use Contexto Quando

Os dados pulam múltiplos níveis — Se as props precisariam passar por 3 ou mais componentes que não as utilizam, o contexto elimina o drilling.

Muitos componentes precisam dos mesmos dados — Tema, usuário, localidade, configuração — o contexto define uma vez e acessa em qualquer lugar.

Construindo componentes compostos — <Tabs> e <Tab> precisam se comunicar sem expor internos como props.

Diferentes subárvores precisam de valores diferentes — O "mais próximo vence" do contexto permite que diferentes seções tenham temas diferentes.

Use Props Quando

Relação direta pai-filho — Um nível de passagem é claro e explícito.

API explícita — Props documentam o que um componente precisa; contexto é implícito.

Máxima segurança de tipos — Props têm melhor suporte a TypeScript por padrão.

Use Stores Quando

Estado verdadeiramente global — Mesmos dados necessários em partes não relacionadas da árvore.

Dados fluem para cima — O contexto só desce; stores funcionam em qualquer direção.

Estado persiste após desmontagens — O contexto desaparece com seu provider; stores vivem de forma independente.

Decisão Rápida

Need to share data?
├─ Direct parent → child? → Props
├─ Skip 2+ levels? → Context
├─ Global / bidirectional? → Stores
└─ Otherwise → Local $state

Equívocos Comuns

"Contexto é estado global"

Não. Contexto tem escopo de subárvore. Diferentes partes da sua aplicação podem ter valores diferentes para a mesma chave. No SvelteKit, layouts aninhados podem substituir o contexto do pai:

<!-- src/routes/+layout.svelte -->
<script>
	import { setContext } from 'svelte'
	setContext('theme', 'light')  // Default for all routes
</script>

<!-- src/routes/admin/+layout.svelte -->
<script>
	import { setContext } from 'svelte'
	setContext('theme', 'dark')  // Override for /admin/* routes
</script>

Páginas públicas recebem 'light', páginas administrativas recebem 'dark'.

"Contexto substitui props"

Não. Contexto complementa props. Use props para comunicação direta pai-filho e APIs explícitas de componentes.

"Contexto é reativo por padrão"

Não. O contexto captura um valor uma única vez. Para contexto reativo, passe objetos com $state dentro. Consulte Tornando o Contexto Reativo.

"Posso definir/obter contexto em qualquer lugar"

Não. Apenas durante a inicialização do componente. Capture os valores durante a inicialização e, em seguida, use-os em qualquer lugar.

Resumo

Contexto resolve o prop drilling — Os dados vão diretamente do provedor ao consumidor, pulando os intermediários.
Flui apenas para baixo — De ancestrais para descendentes. O ancestral mais próximo tem prioridade.
Quatro funções — setContext, getContext, hasContext, getAllContexts.
O momento importa — Deve ser chamado durante a inicialização do componente.
Escolha com sabedoria — Contexto para dados de subárvore, props para comunicação direta, stores para estado global.