Fornecendo Contexto para Componentes Filhos

No artigo anterior, exploramos o que é a API de Contexto e por que ela existe. Vimos como o contexto elimina o prop drilling ao permitir que componentes ancestrais transmitam dados que qualquer descendente pode receber. Agora é hora de dominar a mecânica de fornecer contexto — o ato de estabelecer essa transmissão.

Este artigo foca inteiramente no lado do provedor da equação de contexto. Examinaremos minuciosamente o setContext, entenderemos suas restrições de tempo e por que elas existem, exploraremos que tipos de valores você pode fornecer e desenvolveremos padrões robustos para construir componentes provedores que escalam com sua aplicação.

Ao final deste artigo, você será capaz de configurar contexto com confiança em qualquer cenário, construir componentes provedores reutilizáveis e tomar decisões bem fundamentadas sobre como estruturar o contexto nas suas aplicações.

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

A Função setContext: Uma Análise Profunda

A função setContext é o coração do fornecimento de contexto. Vamos examiná-la minuciosamente para entender não apenas como ela funciona, mas por que funciona da maneira que funciona.

Assinatura da Função

function setContext<T>(key: any, value: T): T

A função aceita dois parâmetros:

key — O identificador do contexto. Pode ser qualquer valor que funcione como chave de um Map JavaScript: strings, Symbols, objetos, números ou até mesmo undefined (embora isso fosse confuso). A chave é como os componentes descendentes vão buscar esse contexto.

value — Os dados reais que você está disponibilizando. Pode ser literalmente qualquer valor JavaScript: primitivos, objetos, arrays, funções, instâncias de classe, Promises, Maps, Sets — qualquer coisa.

Valor de retorno — A função retorna exatamente o mesmo valor que você passou. Isso pode parecer inútil à primeira vista, mas na verdade é bem útil, como veremos.

setContext apenas armazena uma referência — não torna o valor reativo. Se você precisa que os consumidores vejam atualizações, deve usar explicitamente $state e getters. Cobriremos esse padrão em detalhes mais adiante.

Uso Básico

Na forma mais simples, setContext se parece com isso:

<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	setContext('greeting', 'Hello, world!')
</script>

{@render children()}

Após a execução desse código, qualquer componente renderizado dentro deste (via {@render children()}) pode chamar getContext('greeting') para receber a string 'Hello, world!'.

Pense nisso como uma transmissão de rádio: este componente está transmitindo na frequência 'greeting', e qualquer descendente pode sintonizar para receber a mensagem.

Entendendo o Valor de Retorno

O fato de setContext retornar seu valor é um recurso sutil, mas útil. Ele permite que você defina o contexto e mantenha uma referência local em uma única expressão:

<script>
	import { setContext } from 'svelte'

	// Without using return value - two lines
	const config = { apiUrl: '/api', timeout: 5000 }
	setContext('config', config)

	// Using return value - one line, same result
	const config2 = setContext('config', { apiUrl: '/api', timeout: 5000 })

	// Both work identically
	console.log(config === config2) // true (if they were the same call)
</script>

Isso é particularmente útil quando você quer tanto fornecer o contexto quanto usar o valor localmente dentro do componente provedor:

<script>
	import { setContext } from 'svelte'

	// Create and provide the API client, keeping a local reference
	const api = setContext(
		'api',
		new ApiClient({
			baseUrl: 'https://api.example.com',
			timeout: 10000
		})
	)

	// Use it locally in the provider component
	$effect(() => {
		api.healthCheck().then((status) => {
			console.log('API Status:', status)
		})
	})
</script>

Esse padrão mantém seu código DRY — você cria o valor, o fornece e mantém uma referência, tudo em uma única expressão.

Escolhendo a Chave: Nomeando Sua Transmissão

O primeiro argumento de setContext é a chave — um identificador que os descendentes usarão para recuperar o valor do contexto. Pode ser qualquer valor JavaScript que funcione como chave de um Map, mas sua escolha tem implicações para a segurança contra colisões e a experiência do desenvolvedor.

Chaves String (Casos Simples)

Para aplicações pequenas ou funcionalidades isoladas, chaves string funcionam bem e são fáceis de ler:

<script>
	import { setContext } from 'svelte'

	setContext('theme', 'dark')
	setContext('user', { name: 'Alice' })
	setContext('locale', 'en-US')
</script>

Usar strings tem a vantagem de ser legível, fácil de digitar e imediatamente compreensível. A desvantagem? Em aplicações grandes, diferentes partes do seu código podem acidentalmente usar a mesma chave string, causando colisões. Pior ainda, uma biblioteca de terceiros pode usar a mesma chave que o código da sua aplicação.

Chaves Symbol (Recomendado para Bibliotecas)

O uso de Symbols garante unicidade. Mesmo que dois arquivos diferentes criem Symbol('theme'), eles são símbolos diferentes — porque Symbol() gera um novo identificador globalmente único toda vez que é chamado, independentemente da string de descrição que você passa

// src/lib/context/keys.ts
export const THEME_KEY = Symbol('theme')
export const USER_KEY = Symbol('user')
export const CONFIG_KEY = Symbol('config')

<script>
	import { setContext } from 'svelte'
	import { THEME_KEY } from '$lib/context/keys'

	setContext(THEME_KEY, { mode: 'dark', accent: '#3b82f6' })
</script>

Esta é a abordagem recomendada para:

Bibliotecas reutilizáveis que outros irão instalar
Aplicações grandes com múltiplas equipes
Qualquer situação em que você precise garantir que não haja colisões de chave

A string passada para Symbol() é apenas uma descrição para depuração — não afeta a unicidade.

Chaves Object (Avançado)

Você pode até usar objetos como chaves, embora raramente seja necessário:

<script>
	import { setContext } from 'svelte'

	// The object reference IS the key
	const CART_KEY = {}
	setContext(CART_KEY, { items: [] })
</script>

Isso funciona porque o Map do JavaScript usa igualdade de referência para chaves de objeto. No entanto, Symbols geralmente são mais claros para esse propósito.

Quando Usar Cada Tipo de Chave

Cenário	Tipo de Chave Recomendado
Protótipo rápido ou app pequeno	String
Funcionalidade dentro da sua app	String ou Symbol
Biblioteca/pacote compartilhado	Symbol
Projeto TypeScript	`createContext` (abordado em detalhes mais adiante neste artigo)

Se você está usando TypeScript, createContext (Svelte 5.40+) geralmente é a solução preferida. Ela elimina o gerenciamento manual de chaves e fornece inferência completa de tipos. Cobrimos isso em detalhes na seção Contexto Type-Safe com createContext.

O Que Você Pode Fornecer como Contexto?

Você pode fornecer qualquer valor JavaScript como contexto. Vamos examinar diferentes tipos e suas implicações, porque sua escolha afeta significativamente como os consumidores interagem com os dados.

Valores Primitivos

Qualquer primitivo — string, number, boolean, null, undefined, Symbol — pode ser um valor de contexto:

<script>
	import { setContext } from 'svelte'

	setContext('appName', 'BookIt') // string
	setContext('maxUploadSize', 10485760) // number (10MB in bytes)
	setContext('isProduction', true) // boolean
	setContext('deprecatedFeature', null) // null
	setContext('experimentalFlag', undefined) // undefined (rarely useful)
</script>

Característica importante dos primitivos: Eles são passados por valor, o que significa que o contexto captura um instantâneo no momento em que setContext é chamado. Se você modificar a variável original posteriormente, o valor do contexto não muda:

<script>
	import { setContext } from 'svelte'

	let count = 0
	setContext('count', count) // Context captures 0

	count = 100 // This does NOT update the context
	// Descendants still see 0
</script>

Esse comportamento é fundamental para entender: primitivos em contexto são instantâneos estáticos, não valores dinâmicos. Você não pode esperar que eles sejam atualizados automaticamente — este é um dos erros mais comuns de iniciantes.

Se você precisar de reatividade, deve usar objetos com $state, discutido em detalhes no artigo Tornando o Contexto Reativo.

Objetos e Arrays

Objetos e arrays são passados por referência, o que significa que os descendentes recebem exatamente o mesmo objeto na memória:

<script>
	import { setContext } from 'svelte'

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

	// Later modifications ARE visible to descendants
	user.score = 100 // Descendants see { name: 'Alice', score: 100 }

	// BUT: This is a property mutation, not automatic reactivity
	// Components won't re-render automatically unless you use $state
</script>

Esse compartilhamento de referência tem implicações importantes:

Modificações são visíveis — Quando você modifica o objeto, todos os componentes que possuem uma referência enxergam as mudanças
Mas não são automaticamente reativos — O Svelte não sabe que você o modificou; os componentes não vão re-renderizar automaticamente
A identidade é preservada — context.user === user é true; são o mesmo objeto

Para contexto reativo que dispara atualizações na UI, você deve usar $state e getters. Simplesmente mutar propriedades não causará re-renderizações. Cobriremos esse padrão no artigo Tornando o Contexto Reativo.

Ponto de Verificação Conceitual

Antes de continuarmos para tipos de valores mais complexos, vamos fazer uma pausa e consolidar o que aprendemos até agora:

O contexto armazena referências, não assinaturas — setContext captura o que você passa no momento da chamada. Para primitivos, isso é uma cópia do valor; para objetos, é uma referência ao mesmo objeto na memória.
A reatividade deve ser explícita — O Svelte não rastreia automaticamente os valores de contexto. Se você quer que os consumidores vejam atualizações e re-renderizem, você precisa de $state e getters.
Provedores possuem o estado e Consumidores o observam — O componente que chama setContext é responsável pelos dados. Os consumidores os recebem e reagem a eles, mas o Provedor controla quando e como eles mudam.

Com esse modelo mental estabelecido, vamos ver tipos de valores mais poderosos.

Funções

Funções são excelentes valores de contexto, especialmente para fornecer ações. Em vez de apenas fornecer dados, você pode fornecer capacidades:

<script>
	import { setContext } from 'svelte'

	// Simple utility function
	setContext('formatPrice', (cents) => `$${(cents / 100).toFixed(2)}`)

	// Logger with context
	setContext('log', (level, message) => {
		console.log(`[${new Date().toISOString()}] [${level.toUpperCase()}] ${message}`)
	})

	// Navigation helper
	setContext('navigate', (path) => {
		window.history.pushState({}, '', path)
		window.dispatchEvent(new PopStateEvent('popstate'))
	})
</script>

Funções no contexto habilitam o padrão "ações via contexto", onde você fornece não apenas dados, mas capacidades:

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

	let { children } = $props()
	let toasts = $state([])

	function showToast(message, type = 'info', duration = 3000) {
		const id = crypto.randomUUID()
		toasts.push({ id, message, type })

		setTimeout(() => {
			toasts = toasts.filter((t) => t.id !== id)
		}, duration)
	}

	// Provide the action, not the data
	setContext('toast', showToast)
</script>

{@render children()}

<div class="toast-container">
	{#each toasts as toast (toast.id)}
		<div class="toast toast-{toast.type}">{toast.message}</div>
	{/each}
</div>

Os consumidores não precisam saber como os toasts são armazenados ou renderizados — eles simplesmente chamam a função:

<script>
	import { getContext } from 'svelte'

	const toast = getContext('toast')

	function handleSave() {
		// ... save logic
		toast('Document saved successfully!', 'success')
	}
</script>

Esse padrão cria uma separação clara: o provedor possui a implementação, os consumidores apenas usam a capacidade.

Instâncias de Classe

Instâncias de classe funcionam perfeitamente como valores de contexto, habilitando padrões poderosos de encapsulamento:

<script>
	import { setContext } from 'svelte'

	class ApiClient {
		constructor(baseUrl) {
			this.baseUrl = baseUrl
		}

		async get(path) {
			const response = await fetch(`${this.baseUrl}${path}`)
			return response.json()
		}

		async post(path, data) {
			const response = await fetch(`${this.baseUrl}${path}`, {
				method: 'POST',
				headers: { 'Content-Type': 'application/json' },
				body: JSON.stringify(data)
			})
			return response.json()
		}
	}

	// Provide a configured API client instance
	setContext('api', new ApiClient('https://api.example.com'))
</script>

Isso é particularmente poderoso porque:

A classe encapsula funcionalidades relacionadas
A configuração acontece uma única vez no provedor
Todos os descendentes compartilham a mesma instância configurada
Os métodos têm acesso ao estado da instância (como tokens de autenticação)

Classes com propriedades $state se tornam serviços reativos:

<script>
	import { setContext } from 'svelte'

	class CartService {
		items = $state([])

		add(product) {
			this.items.push(product)
		}

		remove(id) {
			this.items = this.items.filter((i) => i.id !== id)
		}

		get total() {
			return this.items.reduce((sum, item) => sum + item.price, 0)
		}

		get count() {
			return this.items.length
		}
	}

	setContext('cart', new CartService())
</script>

Maps, Sets e Outros Tipos Nativos

Qualquer valor JavaScript funciona, incluindo coleções nativas:

<script>
	import { setContext } from 'svelte'

	// Cache using Map
	setContext('cache', new Map())

	// Feature flags using Set
	setContext('enabledFeatures', new Set(['dark-mode', 'beta-search', 'new-checkout']))

	// Regular expression for validation
	setContext('emailPattern', /^[^\s@]+@[^\s@]+\.[^\s@]+$/)

	// Date for "app started at"
	setContext('appStartTime', new Date())
</script>

E as Promises?

Você pode fornecer Promises como contexto, embora isso exija um tratamento cuidadoso:

<script>
	import { setContext } from 'svelte'

	// Provide a Promise for async data
	const userPromise = fetch('/api/user').then((r) => r.json())
	setContext('userPromise', userPromise)
</script>

Os consumidores precisariam aguardá-la:

<script>
	import { getContext } from 'svelte'

	const userPromise = getContext('userPromise')
	let user = $state(null)

	$effect(() => {
		userPromise.then((data) => {
			user = data
		})
	})
</script>

{#if user}
	<p>Welcome, {user.name}!</p>
{:else}
	<p>Loading...</p>
{/if}

No entanto, esse padrão tem desvantagens:

Cada consumidor deve lidar com a complexidade assíncrona
O tratamento de erros fica espalhado pelos consumidores
Nenhum estado de carregamento centralizado

Na maioria dos casos, fornecer Promises diretamente é um code smell. É melhor resolver dados assíncronos no provedor e expor estado reativo com tratamento de carregamento/erros integrado. Veremos esse padrão nos exemplos de provedor.

A Regra de Temporização: Inicialização do Componente

Talvez a regra mais importante sobre setContext seja quando ele pode ser chamado. Entender essa regra — e por que ela existe — vai te poupar de erros confusos e ajudá-lo a projetar provedores melhores.

A Regra

setContext deve ser chamado durante a inicialização do componente — a execução síncrona do seu bloco <script> quando o componente é renderizado pela primeira vez.

O que Significa "Inicialização do Componente"

Quando o Svelte renderiza um componente, ele executa seu bloco <script> de forma síncrona, de cima para baixo. Essa execução inicial e síncrona é a "inicialização do componente". Assim que essa fase é concluída, o componente está "inicializado" e a janela de contexto se fecha.

<script>
	import { setContext } from 'svelte'

	// ═══════════════════════════════════════════
	// COMPONENT INITIALIZATION PHASE
	// (synchronous execution of script block)
	// ═══════════════════════════════════════════

	console.log('1. Start of initialization')

	setContext('a', 'value') // ✅ Valid - during initialization

	function helperThatSetsContext() {
		setContext('b', 'value') // ✅ Valid IF called synchronously below
	}
	helperThatSetsContext() // Called during initialization

	const result = (() => {
		setContext('c', 'value') // ✅ Valid - IIFE runs during initialization
		return 'done'
	})()

	console.log('2. End of initialization')

	// ═══════════════════════════════════════════
	// END OF INITIALIZATION
	// Everything below runs AFTER initialization
	// ═══════════════════════════════════════════

	function handleClick() {
		setContext('d', 'value') // ❌ Invalid - runs on click, after init
	}

	$effect(() => {
		setContext('e', 'value') // ❌ Invalid - effects run after init
	})

	setTimeout(() => {
		setContext('f', 'value') // ❌ Invalid - runs later, after init
	}, 0)

	fetch('/api').then(() => {
		setContext('g', 'value') // ❌ Invalid - runs when Promise resolves
	})
</script>

Por que Essa Restrição Existe

Essa restrição de temporização não é arbitrária — ela é fundamental para o funcionamento do contexto. Vamos entender o porquê examinando a sequência de inicialização do componente.

1. O contexto é estrutural, estabelecido no momento da montagem

O contexto faz parte da estrutura da árvore de componentes, assim como a hierarquia do DOM. Quando um componente é montado, o Svelte precisa saber qual contexto ele fornece para que os componentes filhos possam acessá-lo durante sua inicialização.

Considere esta árvore:

Parent (sets 'user' context)
└── Child (reads 'user' context)

A sequência é:

O pai começa a inicializar
O pai chama setContext('user', userData)
O pai termina de inicializar
O pai renderiza seu template (que inclui o filho)
O filho começa a inicializar
O filho chama getContext('user') — isso deve funcionar!
O filho termina de inicializar

Se o pai definisse o contexto em um manipulador de eventos (após o passo 3), seria tarde demais — o filho já tentou lê-lo no passo 6.

2. Componentes filhos são inicializados imediatamente

Quando o Svelte encontra um componente filho no template, ele inicializa esse filho imediatamente (na mesma execução síncrona). Não há atraso entre "o pai termina" e "o filho começa."

<!-- Parent.svelte -->
<script>
	import { setContext } from 'svelte'
	import Child from './Child.svelte'

	console.log('Parent: before setContext')
	setContext('data', { value: 42 })
	console.log('Parent: after setContext')
</script>

<Child />

<!-- Output:
Parent: before setContext
Parent: after setContext
Child: reading context
Child: got { value: 42 }
-->

3. Previsibilidade e depuração

Se o contexto pudesse ser definido a qualquer momento, seria quase impossível raciocinar sobre se o contexto está disponível. A restrição garante que, assim que um componente é inicializado, todo o contexto de seus ancestrais esteja estabelecido e disponível.

Essa previsibilidade é uma característica, não uma limitação. Você sempre pode contar com o contexto estando disponível (ou não) com base na estrutura da árvore de componentes.

A Mensagem de Erro

Se você violar a regra de temporização, o Svelte lança:

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

Esse erro é seu amigo — significa que você tentou chamar setContext após a janela de inicialização ter se fechado. Ele captura bugs cedo em vez de deixá-los se manifestar como valores "undefined" confusos posteriormente.

Erros Comuns e Correções

Vamos examinar os erros de temporização mais comuns e como corrigi-los adequadamente.

Definindo contexto em um manipulador de eventos

<script>
	import { setContext } from 'svelte'

	// ❌ Wrong - handler runs after initialization
	function handleInit() {
		setContext('late', 'value')
	}
</script>

<button onclick={handleInit}>Initialize</button>

Por que falha: Manipuladores de eventos são executados quando o usuário interage, muito após a inicialização.

Correção: Defina o contexto no nível superior com um contêiner reativo e, em seguida, atualize esse contêiner posteriormente:

<script>
	import { setContext } from 'svelte'

	// ✅ Set during initialization
	let data = $state(null)
	setContext('data', {
		get value() {
			return data
		}
	})

	function handleInit() {
		// Update the state, which is already in context
		data = 'initialized value'
	}
</script>

Definindo contexto após await

<script>
	import { setContext } from 'svelte'

	// ❌ Wrong - code after await runs asynchronously
	async function setup() {
		const response = await fetch('/api/config')
		const config = await response.json()
		setContext('config', config) // Too late!
	}
	setup()
</script>

Por que falha: O await pausa a execução. Quando ela é retomada, a inicialização já terminou.

Correção: Forneça um contêiner reativo de forma síncrona e atualize-o quando os dados chegarem:

<script>
	import { setContext } from 'svelte'

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

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

	// Fetch and update state (this runs async, but context is already set)
	fetch('/api/config')
		.then((r) => r.json())
		.then((data) => {
			config = data
			loading = false
		})
		.catch((err) => {
			error = err.message
			loading = false
		})
</script>

Agora os consumidores podem verificar loading e error enquanto aguardam os dados:

<script>
	import { getContext } from 'svelte'
	const config = getContext('config')
</script>

{#if config.loading}
	<p>Loading configuration...</p>
{:else if config.error}
	<p>Error: {config.error}</p>
{:else}
	<p>API URL: {config.data.apiUrl}</p>
{/if}

Definindo contexto em $effect

<script>
	import { setContext } from 'svelte'

	let { userId } = $props()

	// ❌ Wrong - effects run after initialization
	$effect(() => {
		setContext('userId', userId)
	})
</script>

Por que falha: Efeitos são executados após a montagem do componente, não durante a inicialização.

Correção: Defina o contexto uma vez durante a inicialização. Se o valor puder mudar, use um getter reativo:

<script>
	import { setContext } from 'svelte'

	let { userId } = $props()

	// ✅ Set during initialization with reactive getter
	setContext('user', {
		get id() {
			return userId
		} // Always returns current prop value
	})
</script>

Construindo Componentes Provider

Um provider é qualquer componente que chama setContext() para disponibilizar dados para seus descendentes. Em aplicações SvelteKit, o lugar mais natural para fornecer contexto é nos arquivos de layout, mas você também pode criar componentes provider dedicados para reutilização.

Fornecendo Contexto em Layouts (SvelteKit)

No SvelteKit, os arquivos +layout.svelte envolvem automaticamente todas as páginas em seu segmento de rota. Isso os torna o lugar idiomático para fornecer contexto:

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

	let { children } = $props()

	// Provide theme context to all pages
	setContext('theme', 'dark')
</script>

{@render children()}

Toda página e componente em sua aplicação agora pode acessar o tema via getContext('theme'). Nenhum componente wrapper necessário — o sistema de layout do SvelteKit trata a hierarquia naturalmente.

Para contexto específico de rota, use layouts aninhados:

<!-- src/routes/admin/+layout.svelte -->
<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	// Admin-specific context, only available in /admin/* routes
	setContext('adminConfig', {
		sidebarCollapsed: false,
		permissions: ['read', 'write', 'delete']
	})
</script>

{@render children()}

Componentes Provider Reutilizáveis

Para lógica de contexto que você deseja reutilizar em múltiplos layouts ou aplicações, extraia-a em um componente dedicado:

<!-- src/lib/providers/ThemeProvider.svelte -->
<script>
	import { setContext } from 'svelte'

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

	setContext('theme', theme)
</script>

{@render children()}

Em seguida, use-o em seu layout:

<!-- src/routes/+layout.svelte -->
<script>
	import ThemeProvider from '$lib/providers/ThemeProvider.svelte'

	let { children } = $props()
</script>

<ThemeProvider theme="dark">
	{@render children()}
</ThemeProvider>

Essa abordagem separa a lógica de contexto da estrutura do layout, tornando-a testável e portátil.

Provider com Estado Reativo

A maioria dos providers reais precisa de estado reativo para que os consumidores vejam as atualizações. É aqui que os getters se tornam essenciais:

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

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

	let theme = $state(initialTheme)

	function setTheme(newTheme) {
		theme = newTheme
	}

	function toggleTheme() {
		theme = theme === 'light' ? 'dark' : 'light'
	}

	// Provide reactive getters and actions
	setContext('theme', {
		get current() {
			return theme
		},
		set: setTheme,
		toggle: toggleTheme
	})
</script>

{@render children()}

Por que getters? Observe que usamos get current() { return theme } em vez de apenas current: theme. Isso é crucial para a reatividade:

// ❌ Without getter - captures value at creation time
setContext('theme', {
	current: theme // This is 'light', forever frozen
})

// ✅ With getter - reads current value each time
setContext('theme', {
	get current() {
		return theme
	} // Always returns current $state value
})

Sem o getter, current seria o valor de theme no momento em que o objeto foi criado — ele nunca seria atualizado. Com o getter, acessar current executa a função getter, que lê o valor atual de $state.

Exploraremos esse padrão de reatividade em profundidade no artigo Tornando o Contexto Reativo.

Provider com Efeitos Colaterais

Providers podem gerenciar efeitos colaterais relacionados ao seu contexto. Aqui está um provider de tema que lida com detecção de preferência do sistema, persistência e atualizações do DOM:

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

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

	let theme = $state(initialTheme)
	let resolvedTheme = $state(initialTheme === 'system' ? getSystemTheme() : initialTheme)

	function getSystemTheme() {
		if (typeof window === 'undefined') return 'light'
		return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
	}

	// Watch for system theme changes
	$effect(() => {
		if (theme !== 'system') {
			resolvedTheme = theme
			return
		}

		const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')

		function handleChange(e) {
			resolvedTheme = e.matches ? 'dark' : 'light'
		}

		// Set initial value
		resolvedTheme = mediaQuery.matches ? 'dark' : 'light'

		// Listen for changes
		mediaQuery.addEventListener('change', handleChange)

		return () => {
			mediaQuery.removeEventListener('change', handleChange)
		}
	})

	// Apply theme to document
	$effect(() => {
		document.documentElement.setAttribute('data-theme', resolvedTheme)
	})

	// Persist to localStorage
	$effect(() => {
		if (typeof localStorage !== 'undefined') {
			localStorage.setItem('theme', theme)
		}
	})

	setContext('theme', {
		get preference() {
			return theme
		},
		get resolved() {
			return resolvedTheme
		},
		setPreference(newTheme) {
			theme = newTheme
		},
		toggle() {
			if (theme === 'system') {
				theme = resolvedTheme === 'light' ? 'dark' : 'light'
			} else {
				theme = theme === 'light' ? 'dark' : 'light'
			}
		}
	})
</script>

{@render children()}

Este provider:

Gerencia o estado de preferência de tema ('light', 'dark' ou 'system')
Resolve 'system' para claro/escuro real com base na preferência do sistema operacional
Responde a mudanças de tema do sistema em tempo real
Persiste a preferência no localStorage
Aplica o tema ao DOM via atributo de dados
Expõe uma API limpa para os consumidores

Os consumidores não precisam conhecer nenhum desses detalhes de implementação — eles simplesmente usam o contexto:

<script>
	import { getContext } from 'svelte'
	const theme = getContext('theme')
</script>

<p>Current theme: {theme.resolved}</p>
<button onclick={theme.toggle}>Toggle Theme</button>

Provider com UI

Providers podem renderizar sua própria UI junto com os filhos. Isso é perfeito para funcionalidades como notificações toast, modais ou overlays:

<!-- ToastProvider.svelte -->
<script>
	import { setContext } from 'svelte'
	import { fly, fade } from 'svelte/transition'

	let { children } = $props()

	let toasts = $state([])

	function addToast(message, options = {}) {
		const { type = 'info', duration = 4000 } = options
		const id = crypto.randomUUID()

		toasts.push({ id, message, type })

		if (duration > 0) {
			setTimeout(() => removeToast(id), duration)
		}

		return id
	}

	function removeToast(id) {
		toasts = toasts.filter((t) => t.id !== id)
	}

	setContext('toast', {
		show: addToast,
		success: (msg, opts) => addToast(msg, { ...opts, type: 'success' }),
		error: (msg, opts) => addToast(msg, { ...opts, type: 'error' }),
		warning: (msg, opts) => addToast(msg, { ...opts, type: 'warning' }),
		dismiss: removeToast,
		dismissAll: () => {
			toasts = []
		}
	})
</script>

{@render children()}

<!-- Toast container rendered by the provider -->
{#if toasts.length > 0}
	<div class="toast-container" role="region" aria-label="Notifications">
		{#each toasts as toast (toast.id)}
			<div
				class="toast toast-{toast.type}"
				role="alert"
				in:fly={{ y: 20, duration: 200 }}
				out:fade={{ duration: 150 }}
			>
				<span class="toast-message">{toast.message}</span>
				<button
					class="toast-dismiss"
					onclick={() => removeToast(toast.id)}
					aria-label="Dismiss notification"
				>
					×
				</button>
			</div>
		{/each}
	</div>
{/if}

<style>
	.toast-container {
		position: fixed;
		bottom: 1rem;
		right: 1rem;
		display: flex;
		flex-direction: column;
		gap: 0.5rem;
		z-index: 9999;
	}

	.toast {
		display: flex;
		align-items: center;
		gap: 0.75rem;
		padding: 0.75rem 1rem;
		border-radius: 0.5rem;
		background: white;
		box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
		max-width: 400px;
	}

	.toast-success {
		border-left: 4px solid #10b981;
	}
	.toast-error {
		border-left: 4px solid #ef4444;
	}
	.toast-warning {
		border-left: 4px solid #f59e0b;
	}
	.toast-info {
		border-left: 4px solid #3b82f6;
	}

	.toast-dismiss {
		background: none;
		border: none;
		font-size: 1.25rem;
		cursor: pointer;
		opacity: 0.5;
		padding: 0;
		line-height: 1;
	}

	.toast-dismiss:hover {
		opacity: 1;
	}
</style>

Agora qualquer componente na árvore pode disparar toasts sem conhecer a implementação:

<script>
	import { getContext } from 'svelte'

	const toast = getContext('toast')

	async function handleSave() {
		try {
			await saveDocument()
			toast.success('Document saved!')
		} catch (err) {
			toast.error(`Failed to save: ${err.message}`)
		}
	}
</script>

<button onclick={handleSave}>Save</button>

Compondo Múltiplos Contextos

Aplicações reais frequentemente precisam de múltiplos contextos. No SvelteKit, você pode defini-los todos no seu layout raiz:

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

	let { children } = $props()

	// Set up all app-wide contexts
	let theme = $state('light')
	let user = $state(null)
	let toasts = $state([])

	setContext('theme', {
		get current() {
			return theme
		},
		toggle() {
			theme = theme === 'light' ? 'dark' : 'light'
		}
	})

	setContext('auth', {
		get user() {
			return user
		},
		get isAuthenticated() {
			return user !== null
		},
		login(userData) {
			user = userData
		},
		logout() {
			user = null
		}
	})

	setContext('toast', {
		show(message, type = 'info') {
			const id = crypto.randomUUID()
			toasts.push({ id, message, type })
			setTimeout(() => {
				toasts = toasts.filter((t) => t.id !== id)
			}, 3000)
		}
	})
</script>

{@render children()}

<!-- Toast UI -->
{#each toasts as toast (toast.id)}
	<div class="toast toast-{toast.type}">{toast.message}</div>
{/each}

Para aplicações complexas, você pode extrair cada contexto em seu próprio módulo e compô-los:

<!-- src/routes/+layout.svelte -->
<script>
	import { setupThemeContext } from '$lib/context/theme.svelte'
	import { setupAuthContext } from '$lib/context/auth.svelte'
	import { setupToastContext } from '$lib/context/toast.svelte'

	let { children } = $props()

	// Each function calls setContext internally
	setupThemeContext()
	setupAuthContext()
	const { toasts } = setupToastContext()
</script>

{@render children()}

{#each toasts as toast (toast.id)}
	<div class="toast">{toast.message}</div>
{/each}

Cada função setupXContext encapsula a configuração do contexto, o gerenciamento de estado e os efeitos colaterais para que seu layout possa se concentrar em compor providers em vez de detalhes de implementação:

// src/lib/context/theme.svelte.ts
import { setContext } from 'svelte'

export function setupThemeContext(initial = 'light') {
	let theme = $state(initial)

	const context = {
		get current() {
			return theme
		},
		toggle() {
			theme = theme === 'light' ? 'dark' : 'light'
		}
	}

	setContext('theme', context)
	return context
}

Esse padrão de funções de configuração se destaca para contextos não visuais e escala de forma limpa à medida que os aplicativos crescem, melhorando a organização e a reutilização.

Ao fornecer múltiplos contextos, a ordem das chamadas setContext importa. Os componentes filhos leem o contexto durante sua inicialização, então qualquer contexto do qual dependam deve ser configurado antes de serem renderizados.

Fornecendo Múltiplos Valores de Contexto

Quando um componente precisa fornecer vários elementos de contexto, você tem escolhas arquiteturais a fazer. Vamos examinar as estratégias e quando usar cada uma.

Estratégia 1: Objeto de Contexto Único Combinado

Agrupe valores relacionados em um único contexto:

<script>
	import { setContext } from 'svelte'

	let user = $state({ name: 'Alice', email: 'alice@example.com' })
	let preferences = $state({ theme: 'dark', language: 'en' })
	let permissions = $state(['read', 'write'])

	setContext('app', {
		get user() {
			return user
		},
		get preferences() {
			return preferences
		},
		get permissions() {
			return permissions
		},

		updateUser(updates) {
			user = { ...user, ...updates }
		},
		updatePreferences(updates) {
			preferences = { ...preferences, ...updates }
		},

		hasPermission(perm) {
			return permissions.includes(perm)
		}
	})
</script>

Vantagens:

Importação única para os consumidores: const app = getContext('app')
Claro o que está disponível: um objeto com tudo
Mais fácil de garantir consistência entre valores relacionados

Desvantagens:

Menos granular: qualquer alteração em qualquer valor afeta todos os consumidores
Mais difícil de substituir apenas uma parte em uma subárvore
Pode se tornar difícil de gerenciar à medida que cresce

Melhor para: Dados fortemente acoplados que mudam juntos e são consumidos juntos.

Estratégia 2: Múltiplos Contextos Separados

Cada preocupação recebe sua própria chave de contexto:

<script>
	import { setContext } from 'svelte'

	let user = $state({ name: 'Alice', email: 'alice@example.com' })
	let preferences = $state({ theme: 'dark', language: 'en' })
	let permissions = $state(['read', 'write'])

	setContext('user', {
		get data() {
			return user
		},
		update(updates) {
			user = { ...user, ...updates }
		}
	})

	setContext('preferences', {
		get data() {
			return preferences
		},
		update(updates) {
			preferences = { ...preferences, ...updates }
		}
	})

	setContext('permissions', {
		get list() {
			return permissions
		},
		has(perm) {
			return permissions.includes(perm)
		}
	})
</script>

Vantagens:

Granular: componentes assinam apenas o que precisam
Cada um pode ser substituído independentemente em subárvores
Separação de responsabilidades mais clara
Escala melhor conforme a aplicação cresce

Desvantagens:

Mais importações para consumidores que precisam de múltiplos contextos
Mais chaves para gerenciar e documentar

Melhor para: Dados fracamente acoplados que mudam independentemente ou são consumidos por componentes diferentes.

Estratégia 3: Abordagem Híbrida

Combine dados relacionados, separe preocupações não relacionadas:

<script>
	import { setContext } from 'svelte'

	// Auth-related (tightly coupled)
	let user = $state(null)
	let isAuthenticated = $derived(user !== null)

	setContext('auth', {
		get user() {
			return user
		},
		get isAuthenticated() {
			return isAuthenticated
		},
		login(userData) {
			user = userData
		},
		logout() {
			user = null
		}
	})

	// UI preferences (separate concern)
	let theme = $state('light')
	let sidebarCollapsed = $state(false)

	setContext('ui', {
		get theme() {
			return theme
		},
		get sidebarCollapsed() {
			return sidebarCollapsed
		},
		setTheme(t) {
			theme = t
		},
		toggleSidebar() {
			sidebarCollapsed = !sidebarCollapsed
		}
	})

	// Feature flags (separate concern)
	let flags = $state(new Set(['beta-search']))

	setContext('features', {
		isEnabled(flag) {
			return flags.has(flag)
		},
		enable(flag) {
			flags.add(flag)
		},
		disable(flag) {
			flags.delete(flag)
		}
	})
</script>

Esta abordagem agrupa dados relacionados enquanto mantém preocupações não relacionadas separadas.

Guia de Decisão

Use esta tabela para decidir como estruturar seu contexto:

Pergunta	Se Sim	Se Não
Os dados mudam juntos?	Combine	Separe
São consumidos juntos?	Combine	Separe
Subárvores podem precisar de valores diferentes?	Separe	Qualquer
Está crescendo muito (>5 propriedades)?	Separe em grupos lógicos	Qualquer
Equipes diferentes gerenciam partes diferentes?	Separe	Qualquer

Context Tipado com createContext

O Svelte 5.40 introduziu o createContext, uma API criada especificamente para resolver as deficiências ergonômicas do gerenciamento manual de chaves. Se você esteve acompanhando, já viu como setContext e getContext funcionam com chaves arbitrárias (strings, Symbols, objetos). Embora poderosos, essa abordagem tem atritos: você deve gerenciar as chaves por conta própria, o TypeScript não consegue inferir tipos automaticamente, e um contexto ausente falha silenciosamente com undefined.

O createContext resolve todos esses problemas gerando um par correspondente de funções getter e setter que compartilham uma chave interna garantidamente única. Você nunca vê ou gerencia a chave — ela é tratada por você.

Por que createContext Existe

Antes do createContext, o padrão idiomático em TypeScript era assim:

// keys.ts
export const USER_KEY = Symbol('user')

// types.ts
export interface User {
	id: string
	name: string
	role: 'admin' | 'user'
}

// provider.svelte
import { setContext } from 'svelte'
import { USER_KEY, type User } from './types'
setContext(USER_KEY, user)

// consumer.svelte
import { getContext } from 'svelte'
import { USER_KEY, type User } from './types'
const user = getContext(USER_KEY) as User // Manual type assertion!

Isso funciona, mas observe os pontos problemáticos:

Sobrecarga no gerenciamento de chaves — Você deve exportar o Symbol e importá-lo em todos os lugares
Asserções de tipo necessárias — getContext retorna unknown, então você faz o cast manualmente
Falhas silenciosas — Se nenhum provedor definiu o contexto, você obtém undefined sem aviso
Importações espalhadas — Os consumidores precisam tanto da chave quanto do tipo

O createContext elimina tudo isso ao agrupar geração de chave, inferência de tipo e validação em tempo de execução em uma única API.

Como createContext Funciona

A assinatura da função é direta:

function createContext<T>(defaultValue?: T): [getter: () => T, setter: (value: T) => T]

Quando você chama createContext<T>(), o Svelte:

Gera uma chave interna única (você nunca a vê)
Retorna uma função getter que recupera o contexto com essa chave
Retorna uma função setter que armazena o contexto com essa chave
Configura o TypeScript para que ambas as funções conheçam o tipo T

O getter e o setter estão vinculados à mesma chave oculta, portanto sempre correspondem entre si.

Uso Básico

Aqui está o padrão completo:

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

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

// createContext returns a [getter, setter] tuple
// The generic type parameter flows to both functions
export const [getUser, setUser] = createContext<User>()

No seu componente provedor, você chama o setter durante a inicialização:

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

	let { user, children } = $props()

	// TypeScript ensures `user` matches the User interface
	// If you pass the wrong shape, you get a compile error
	setUser(user)
</script>

{@render children()}

Nos componentes consumidores, você chama o getter:

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

	// No type assertion needed—TypeScript knows this is User
	const user = getUser()

	// Full autocomplete and type checking
	console.log(user.name) // ✅ Works
	console.log(user.foo) // ❌ Type error: Property 'foo' does not exist
</script>

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

O ponto central é que o tipo flui automaticamente. Você define User uma vez, passa para o createContext, e tanto o setter quanto o getter o herdam. Sem asserções manuais, sem margem para incompatibilidades de tipo.

Benefícios em Relação ao Gerenciamento Manual de Chaves

Vamos examinar cada vantagem em detalhes:

Nenhuma colisão de chave possível

Com chaves manuais, você é responsável pela unicidade:

setContext('user', userData) // What if another library uses 'user'?

Mesmo com Symbols, você deve garantir que o mesmo Symbol seja usado em todos os lugares. Com createContext, a chave é interna e gerada de forma nova a cada chamada de createContext(). Duas chamadas separadas de createContext() produzem dois canais de contexto completamente independentes, mesmo que tenham o mesmo tipo.

Inferência de tipo completa sem asserções

Com chaves manuais, o TypeScript não consegue saber qual tipo você armazenou:

const user = getContext('user') as User // You're telling TypeScript to trust you

Asserções de tipo são um code smell — elas ignoram as verificações de segurança do compilador. Se você alterar a interface User mas esquecer de atualizar um consumidor, a asserção mente silenciosamente.

Com createContext, o tipo é aplicado em ambas as extremidades:

const user = getUser() // Type is automatically User, verified by the compiler

Se você alterar a interface User, o TypeScript detecta quaisquer incompatibilidades em tempo de compilação.

Lança exceção em contexto ausente (comportamento fail-fast)

Com getContext, um contexto ausente retorna undefined silenciosamente:

const user = getContext('user')
// If no provider set 'user', this is undefined
// Your code might crash later with "Cannot read property 'name' of undefined"

Essa falha tardia dificulta a depuração — o erro aparece longe do problema real (o provedor ausente).

Com o getter do createContext (quando nenhum padrão é fornecido), um contexto ausente lança uma exceção imediatamente:

const user = getUser()
// If no provider called setUser(), this throws:
// "Error: Context not found: user"

O erro aponta diretamente para o problema: você tentou ler um contexto que nunca foi definido. Esse comportamento fail-fast captura bugs durante o desenvolvimento em vez de em produção.

Importações mais limpas e intencionais

O próprio padrão de importação comunica a intenção:

// Manual approach - what is USER_KEY? What type does it hold?
import { getContext } from 'svelte'
import { USER_KEY } from '$lib/context/keys'
const user = getContext(USER_KEY)

// createContext approach - the function name tells you exactly what you're getting
import { getUser } from '$lib/context/user'
const user = getUser()

O nome getUser é autodocumentado. Você não precisa rastrear definições de chave para entender qual contexto está acessando.

Fornecendo Valores Padrão

Às vezes você quer que o contexto seja opcional e que os componentes funcionem mesmo sem um provedor. O createContext suporta isso com um valor padrão opcional:

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

Agora o comportamento muda:

Se um ancestral chamou setConfig(customConfig), getConfig() retorna essa configuração personalizada
Se nenhum ancestral definiu o contexto, getConfig() retorna o padrão em vez de lançar uma exceção

Isso é útil para configurações que devem ter padrões sensatos, mas que podem ser substituídos:

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

	// Works even without a ConfigProvider in the tree
	const config = getConfig()
</script>

<p>API URL: {config.apiUrl}</p>

O valor padrão é capturado quando createContext é chamado. Se você precisar que o padrão seja reativo ou computado, será necessária uma abordagem diferente — tipicamente um provedor que esteja sempre presente no seu layout.

Combinando createContext com Estado Reativo

createContext gerencia as chaves e a tipagem, mas não torna os valores reativos por conta própria. Para contexto reativo, você o combina com $state e getters, assim como com chaves manuais.

Aqui está um padrão completo que se tornou idiomático em projetos Svelte 5 com TypeScript:

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

// 1. Define the context interface
// Using readonly for values that consumers shouldn't mutate directly
export interface CounterContext {
	readonly count: number
	increment(): void
	decrement(): void
	reset(): void
}

// 2. Create the typed getter/setter pair
export const [getCounter, setCounter] = createContext<CounterContext>()

// 3. Factory function that creates and provides the context
export function createCounterContext(initial = 0) {
	let count = $state(initial)

	// setCounter returns what you pass it, so we can return it from the factory
	return setCounter({
		get count() {
			return count
		},
		increment() {
			count++
		},
		decrement() {
			count--
		},
		reset() {
			count = initial
		}
	})
}

Este padrão tem três partes:

Interface — Define a forma do seu contexto, com readonly para valores que os consumidores não devem modificar
Chamada de createContext — Gera o getter/setter tipado
Função de fábrica — Cria o estado reativo e chama o setter

A função de fábrica é chamada durante a inicialização do componente:

<!-- CounterProvider.svelte -->
<script lang="ts">
	import { createCounterContext } from '$lib/context/counter.svelte'

	let { initial = 0, children } = $props()

	// Creates state and provides context in one call
	createCounterContext(initial)
</script>

{@render children()}

Os consumidores obtêm total segurança de tipos e reatividade:

<script lang="ts">
	import { getCounter } from '$lib/context/counter.svelte'

	const counter = getCounter()
</script>

<!-- Reactive: updates when count changes -->
<p>Count: {counter.count}</p>

<button onclick={counter.increment}>+</button>
<button onclick={counter.decrement}>-</button>
<button onclick={counter.reset}>Reset</button>

Quando Usar createContext vs Chaves Manuais

Use createContext quando:

Você está usando TypeScript e quer segurança de tipos
Você quer comportamento fail-fast para contexto ausente
Você prefere imports autodocumentados (getUser() vs getContext(USER_KEY))
Você está construindo uma biblioteca e quer garantir que não haja colisões de chaves

Mantenha chaves manuais quando:

Você não está usando TypeScript
Você precisa que a chave seja um valor específico (raro, mas possível para interoperabilidade)
Você está trabalhando com código existente que já usa chaves manuais

Para novos projetos TypeScript, createContext é o padrão recomendado.

Padrões de Organização de Contexto

À medida que sua aplicação cresce, a forma como você organiza o código de contexto importa para a manutenibilidade. Vamos explorar padrões comuns.

Padrão 1: Co-localizado com a Funcionalidade

Mantenha os arquivos de contexto junto à funcionalidade que eles servem:

src/features/
├── auth/
│   ├── context.svelte.ts      # Auth context definition
│   ├── AuthProvider.svelte    # Provider component
│   ├── LoginForm.svelte
│   ├── LogoutButton.svelte
│   └── index.ts               # Public exports
├── cart/
│   ├── context.svelte.ts
│   ├── CartProvider.svelte
│   ├── CartDrawer.svelte
│   └── index.ts

Vantagens:

O contexto fica próximo de seus consumidores
Fácil de entender os limites das funcionalidades
Funcionalidades autocontidas e portáteis

Ideal para: Arquitetura baseada em funcionalidades, micro-frontends, equipes grandes.

Padrão 2: Diretório de Contexto Centralizado

Todo o contexto em um único local:

src/lib/context/
├── auth.svelte.ts
├── cart.svelte.ts
├── theme.svelte.ts
├── toast.svelte.ts
└── index.ts       # Re-exports all contexts

Vantagens:

Fácil de visualizar todo o contexto disponível
Imports simples: import { getAuth, getCart } from '$lib/context'
Bom para aplicações menores

Ideal para: Aplicações menores, desenvolvedores solo, prototipação rápida.

Padrão 3: Separação de Contexto e Provedor

Separa a definição do contexto do componente provedor:

src/lib/
├── context/
│   ├── auth.ts            # Types and createContext
│   ├── cart.ts
│   └── index.ts
├── providers/
│   ├── AuthProvider.svelte
│   ├── CartProvider.svelte
│   └── AppProviders.svelte  # Composes all providers

Vantagens:

Clara separação de responsabilidades
Os tipos de contexto podem ser importados sem o overhead do componente
Os componentes provedores podem ser testados de forma independente

Ideal para: Aplicações de médio a grande porte com provedores complexos.

Conclusão

Prover contexto é fundamentalmente um ato de declaração arquitetural. Quando você chama setContext, não está apenas passando dados — está estabelecendo um contrato com cada componente descendente: "Esta informação está disponível aqui, e você pode depender dela." A restrição de tempo (somente na inicialização) não é uma limitação, mas uma característica que garante que esse contrato seja confiável e previsível.

Os padrões explorados neste artigo — desde a provisão simples de valores até provedores complexos com estado reativo e efeitos colaterais — todos servem ao mesmo objetivo: disponibilizar dados para os componentes que precisam deles sem criar acoplamento por meio de componentes intermediários. Seja fornecendo um objeto de configuração simples ou um serviço completo com métodos, efeitos e UI, o mecanismo fundamental permanece o mesmo.

A introdução de createContext no Svelte 5.40 representa uma maturação desses padrões, eliminando o overhead de gerenciamento de chaves e fornecendo segurança de tipos nativamente. Mas mesmo sem ele, a combinação de chaves Symbol, funções de fábrica e interfaces tipadas fornece as ferramentas para construir sistemas de contexto robustos e manuteníveis.

Com esses padrões de provedor dominados, o próximo passo é entender como consumir contexto de forma eficaz — tratando a ausência de contexto de maneira elegante, construindo utilitários reutilizáveis e evitando as sutis armadilhas de reatividade que podem surpreender até desenvolvedores experientes.

Principais Conclusões

Prover contexto de forma eficaz requer a compreensão de vários conceitos-chave:

setContext(key, value) estabelece um contexto que os descendentes podem acessar. Ele retorna o valor passado, útil para manter referências locais.
Qualquer valor JavaScript pode ser fornecido: primitivos, objetos, funções, instâncias de classes e muito mais. Objetos são compartilhados por referência; primitivos são snapshots estáticos.
O momento é crítico: setContext deve ser chamado durante a inicialização do componente — a execução síncrona do seu bloco de script. Manipuladores de eventos, efeitos e código assíncrono são executados tarde demais.
Use getters para reatividade: get current() { return theme } lê o valor atual a cada acesso; current: theme captura o valor inicial para sempre.
Componentes provedores encapsulam a configuração do contexto. Eles podem incluir estado reativo, efeitos colaterais e até sua própria UI (como contêineres de toast).
Múltiplos valores de contexto podem ser organizados como um único objeto combinado (para dados fortemente acoplados) ou contextos separados (para preocupações independentes).
createContext (Svelte 5.40+) elimina o gerenciamento de chaves, fornece segurança de tipos e lança exceções em contexto ausente para detecção antecipada de erros.
Padrões de organização variam desde co-localização com funcionalidades até diretórios centralizados, dependendo do tamanho e da arquitetura da sua aplicação.

O Que Vem a Seguir

Agora que você pode prover contexto, aprenda como recebê-lo em seus componentes em Consumindo Contexto, cobrindo getContext, tratamento de contexto ausente e padrões práticos de acesso.

Veja Também

Documentação Oficial

API setContext — Referência da API
API createContext — Contexto com segurança de tipos
Contexto Svelte — Guia oficial

Fornecendo Contexto para Componentes Filhos

A Função setContext: Uma Análise Profunda

Assinatura da Função

Uso Básico

Entendendo o Valor de Retorno

Escolhendo a Chave: Nomeando Sua Transmissão

Chaves String (Casos Simples)

Chaves Symbol (Recomendado para Bibliotecas)

Chaves Object (Avançado)

Quando Usar Cada Tipo de Chave

O Que Você Pode Fornecer como Contexto?

Valores Primitivos

Objetos e Arrays

Ponto de Verificação Conceitual

Funções

Instâncias de Classe

Maps, Sets e Outros Tipos Nativos

E as Promises?

A Regra de Temporização: Inicialização do Componente

A Regra

O que Significa "Inicialização do Componente"

Por que Essa Restrição Existe

1. O contexto é estrutural, estabelecido no momento da montagem

2. Componentes filhos são inicializados imediatamente

3. Previsibilidade e depuração

A Mensagem de Erro

Erros Comuns e Correções

Definindo contexto em um manipulador de eventos

Definindo contexto após await

Definindo contexto em $effect

Construindo Componentes Provider

Fornecendo Contexto em Layouts (SvelteKit)

Componentes Provider Reutilizáveis

Provider com Estado Reativo

Provider com Efeitos Colaterais

Provider com UI

Compondo Múltiplos Contextos

Fornecendo Múltiplos Valores de Contexto

Estratégia 1: Objeto de Contexto Único Combinado

Estratégia 2: Múltiplos Contextos Separados

Estratégia 3: Abordagem Híbrida

Guia de Decisão

Context Tipado com createContext

Por que createContext Existe

Como createContext Funciona

Uso Básico

Benefícios em Relação ao Gerenciamento Manual de Chaves

Nenhuma colisão de chave possível

Inferência de tipo completa sem asserções

Lança exceção em contexto ausente (comportamento fail-fast)

Importações mais limpas e intencionais

Fornecendo Valores Padrão

Combinando createContext com Estado Reativo

Quando Usar createContext vs Chaves Manuais

Padrões de Organização de Contexto

Padrão 1: Co-localizado com a Funcionalidade

Padrão 2: Diretório de Contexto Centralizado

Padrão 3: Separação de Contexto e Provedor

Conclusão

Principais Conclusões

O Que Vem a Seguir

Veja Também

Documentação Oficial

Artigos Relacionados