Muitos Mecanismos, Uma Decisão

O Svelte fornece múltiplos mecanismos para compartilhar dados entre componentes: props, context, stores, eventos, estado em nível de módulo e pontos de integração com o carregamento de dados do SvelteKit. Cada um existe por razões específicas, se destaca em cenários particulares e carrega trade-offs distintos. Em vez de enxergá-los como opções concorrentes onde uma é "melhor", entender os pontos fortes de cada padrão ajuda você a selecionar a ferramenta certa para cada situação.

Este guia abrangente apresenta uma comparação equilibrada de todos os padrões de gerenciamento de estado no Svelte 5. Você verá os mesmos problemas resolvidos com abordagens diferentes, entenderá os trade-offs envolvidos por meio de diagramas visuais e desenvolverá intuição para quando cada padrão brilha. Seja construindo sua primeira aplicação Svelte ou arquitetando um sistema complexo em produção, este guia fornece o framework de decisão que você precisa.

Ao final, você terá clareza sobre quando o context se destaca, quando os stores fazem mais sentido, quando manter props simples e quando recorrer a algo completamente diferente.

O Panorama do Gerenciamento de Estado

Antes de mergulhar nas comparações, vamos estabelecer o que cada padrão oferece e como eles se relacionam entre si. Entender esse panorama é a base para tomar boas decisões arquiteturais.

Visão Geral dos Padrões

Padrão	Escopo	Direção	Reatividade	Segurança SSR
Props	Pai → filho direto	Descendo (um nível)	Automática	✅ Seguro
Context	Ancestral → qualquer descendente	Descendo (múltiplos níveis)	Manual ($state)	✅ Seguro
Stores	Em qualquer lugar no escopo do módulo	Qualquer direção	Embutida	⚠️ Requer cuidado
Events	Filho → pai	Subindo (um nível)	N/A	✅ Seguro
Bindable Props	Pai ↔ filho	Bidirecional	Automática	✅ Seguro
Module State	Todos os importadores	Qualquer direção	Manual ($state)	❌ Perigoso
SvelteKit Load	Rota → página/layout	Servidor → Cliente	Via props	✅ Seguro

Cada linha representa uma abordagem fundamentalmente diferente para o mesmo problema: levar dados de onde eles existem para onde são necessários.

Arquitetura Visual

O diagrama a seguir mostra como os dados fluem por diferentes padrões em uma aplicação Svelte típica:

As setas sólidas representam fluxo de dados explícito (props, eventos), enquanto as setas tracejadas representam fluxo implícito (context). Observe como o context "tunela" pelos componentes intermediários, enquanto as props devem passar por cada nível.

Entendendo os Modelos Mentais

Antes de comparar os padrões, vamos entender como cada um move conceitualmente os dados pela sua aplicação. Esse modelo mental é essencial para escolher o padrão correto.

Direções do Fluxo de Dados

Cada padrão atende a uma necessidade de comunicação específica:

Props são contratos explícitos entre pai e filho. O filho declara o que precisa e o pai fornece. Essa explicitude torna os componentes autodocumentados, mas requer passar os dados por cada componente intermediário.

Context cria um canal implícito de qualquer ancestral para qualquer descendente. Os componentes intermediários não precisam conhecer ou encaminhar os dados. Isso resolve o prop drilling, mas introduz dependências ocultas.

Events (callback props no Svelte 5) notificam os pais sobre ações nos filhos. São o complemento das props, completando o ciclo de comunicação pai-filho.

Stores saem completamente da árvore de componentes. Qualquer código que importa um store compartilha o mesmo estado reativo, possibilitando padrões impossíveis com comunicação restrita à árvore.

Visualização de Escopo

Entender o escopo é crítico, especialmente para segurança em SSR:

Este diagrama ilustra por que o estado em nível de módulo é perigoso no SSR: tanto a Requisição A quanto a Requisição B compartilham o mesmo estado do módulo, podendo vazar dados entre usuários. O context cria instâncias isoladas por árvore de componentes, tornando-o inerentemente seguro para SSR.

Context vs Props

Esta é a comparação que a maioria dos desenvolvedores encontra primeiro. Quando você deve usar context em vez de passar props?

A Diferença Central

Props fluem dados explicitamente do pai para o filho imediato. Context flui dados implicitamente de qualquer ancestral para qualquer descendente.

Observe como com props, todo componente intermediário deve lidar com os dados (amarelo). Com context, os intermediários ficam completamente alheios (cinza).

Quando Props se Destacam

Props ganham na comunicação direta pai-filho onde a explicitude importa:

<!-- ProductCard.svelte -->
<script lang="ts">
	import ProductImage from './ProductImage.svelte'
	import ProductTitle from './ProductTitle.svelte'
	import ProductPrice from './ProductPrice.svelte'

	interface Props {
		product: Product
	}

	let { product }: Props = $props()
</script>

<article class="product-card">
	<ProductImage src={product.image} alt={product.name} />
	<ProductTitle title={product.name} />
	<ProductPrice amount={product.price} currency="USD" />
</article>

Cada filho declara exatamente o que precisa. O contrato é explícito, tipado e documentado pelo próprio código. Você pode ler ProductImage.svelte e entender imediatamente seus requisitos de dados sem precisar procurar nos componentes ancestrais.

Pontos fortes das Props:

Explícitas — Você vê exatamente quais dados um componente precisa ao ler suas props
Type-safe — Suporte completo a TypeScript com autocomplete e verificação de erros na IDE
Descobríveis — Props aparecem nas assinaturas dos componentes, tornando as APIs autodocumentadas
Testáveis — Fácil de fornecer props diferentes nos testes sem precisar mockar context
Refatoráveis — Renomeie uma prop e o TypeScript mostra todos os usos

Quando Context Vence

Context vence quando os dados precisam pular múltiplos níveis, mantendo os componentes intermediários limpos:

<!-- The Prop Drilling Problem -->
<App>
	<!-- has user -->
	<Layout {user}>
		<!-- passes through -->
		<Sidebar {user}>
			<!-- passes through -->
			<NavMenu {user}>
				<!-- passes through -->
				<UserAvatar {user} />
				<!-- finally uses it -->
			</NavMenu>
		</Sidebar>
	</Layout>
</App>

<!-- The Context Solution -->
<App>
	<!-- setContext('user', user) -->
	<Layout>
		<!-- clean! -->
		<Sidebar>
			<!-- clean! -->
			<NavMenu>
				<!-- clean! -->
				<UserAvatar />
				<!-- getContext('user') -->
			</NavMenu>
		</Sidebar>
	</Layout>
</App>

A versão com context elimina quatro props intermediárias. Layout, Sidebar e NavMenu permanecem desacoplados dos dados de usuário que não utilizam.

Pontos fortes do Context:

Sem drilling — Componentes intermediários ficam limpos e focados
Desacoplado — Componentes declaram apenas o que realmente usam
Escopado — Diferentes subárvores podem ter valores diferentes via shadowing de context
Flexível — Adicione novos consumidores de context sem modificar os intermediários

Pontos fracos do Context:

Implícito — É necessário ler o código para saber qual context um componente precisa
Menos descobrível — Dependências não estão na assinatura do componente
Overhead de testes — São necessários wrappers de provider nos testes

Resumo dos Trade-offs

Aspecto	Props	Context
Dependências	✔ Explícitas (autodocumentadas)	✘ Implícitas (requisitos ocultos)
TypeScript	✔ Melhor inferência	⚠️ Bom, mas menos descobrível
Rastreamento do fluxo	✔ Mais fácil de rastrear	⚠️ Requer verificar providers
Reusabilidade	✔ Sem dependência de context	✘ Acoplado à estrutura do context
Componentes intermediários	✘ Devem passar por todos	✔ Pula os intermediários
Acoplamento	✘ Intermediários acoplados aos dados	✔ Reduz o acoplamento
Dados ambientais	⚠️ Verboso para tema/auth/locale	✔ Melhor adequação

Guia de Melhor Adequação:

Território das Props	Território do Context
Pai-filho direto	3+ níveis de profundidade
1-2 níveis de profundidade	Componentes compostos
API pública de biblioteca de componentes	Dados ambientais de Tema/Auth/Locale

Exemplo Lado a Lado: Dados de Tema

Vejamos as duas abordagens resolvendo o mesmo problema:

Abordagem com Props:

<!-- App.svelte -->
<script>
	let theme = $state({ mode: 'light', primary: '#3b82f6' })
</script>

<Layout {theme}>
	<slot />
</Layout>

<!-- Layout.svelte -->
<script>
	let { theme, children } = $props()
</script>

<Header {theme} />
<main>{@render children()}</main>
<Footer {theme} />

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

<nav style:background={theme.mode === 'dark' ? '#1f2937' : '#fff'}>
	<Logo {theme} />
	<Navigation {theme} />
	<ThemeToggle {theme} />
</nav>

Abordagem com Context:

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

	let theme = $state({ mode: 'light', primary: '#3b82f6' })

	setContext('theme', {
		get mode() {
			return theme.mode
		},
		get primary() {
			return theme.primary
		},
		toggle() {
			theme.mode = theme.mode === 'light' ? 'dark' : 'light'
		}
	})
</script>

<Layout>
	<slot />
</Layout>

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

<Header />
<main>{@render children()}</main>
<Footer />

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

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

<nav style:background={theme.mode === 'dark' ? '#1f2937' : '#fff'}>
	<Logo />
	<Navigation />
	<ThemeToggle />
</nav>

A abordagem com context resulta em componentes intermediários mais limpos (Layout não menciona mais o tema), enquanto a abordagem com props torna as dependências de tema visíveis na interface de cada componente.

A Abordagem Híbrida

Aplicações em produção frequentemente combinam ambos os padrões de forma estratégica:

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

	// Props for this component's direct concerns
	let { product, variant = 'default' } = $props()

	// Context for cross-cutting concerns
	const cart = getContext('cart')
	const theme = getContext('theme')
</script>

<article class="card {variant}" style="--bg: {theme.colors.surface}">
	<h3>{product.name}</h3>
	<p>${product.price}</p>
	<button onclick={() => cart.addItem(product)}>Add to Cart</button>
</article>

Os dados do produto (específicos deste card) chegam via props. Preocupações transversais (carrinho, tema) chegam via context. Essa separação mantém a API primária do componente explícita, evitando o prop drilling para dados ambientais.

Guia de Decisão: Props vs Context

Cenário	Melhor Escolha	Raciocínio
Pai-filho direto	Props	Claro, explícito e totalmente tipado
1-2 níveis de profundidade	Props	O overhead do drilling é gerenciável
3+ níveis de profundidade	Context	Evita acoplar componentes intermediários
API pública de biblioteca de componentes	Props	Consumidores precisam de interface explícita e documentada
Estado interno de componentes compostos	Context	Detalhe de implementação, não faz parte da API
Valores diferentes por subárvore	Context	O shadowing de context possibilita isso naturalmente
Máxima segurança de tipos necessária	Props	Melhor suporte na IDE e refatoração
Tema, auth, locale	Context	Dados ambientais usados em toda a subárvore

Context vs Stores

Stores ($state em nível de módulo ou stores reativos do Svelte) oferecem outra abordagem para estado compartilhado. A comparação aqui é mais matizada porque stores e context resolvem problemas que se sobrepõem, mas são distintos.

A Diferença Central

Context é scoped por árvore: ele flui pela hierarquia de componentes e pode ter valores diferentes em subárvores diferentes. Stores são scoped por importação: qualquer módulo que importa o store vê o mesmo valor.

Com context, a Subárvore B pode sobrescrever o tema com 'dark', e todos os seus descendentes veem o tema escuro enquanto a Subárvore A continua vendo 'light'. Com stores, todos veem o mesmo valor — não há como ter temas diferentes em partes diferentes da aplicação.

Quando Stores se Destacam

Stores brilham para estado verdadeiramente global que é idêntico em todos os lugares:

// src/lib/stores/notifications.svelte.ts
interface Notification {
	id: string
	message: string
	type: 'info' | 'success' | 'error'
}

let notifications = $state<Notification[]>([])

export function addNotification(message: string, type: Notification['type'] = 'info') {
	const id = crypto.randomUUID()
	notifications.push({ id, message, type })

	setTimeout(() => removeNotification(id), 5000)
}

export function removeNotification(id: string) {
	const index = notifications.findIndex((n) => n.id === id)
	if (index !== -1) {
		notifications.splice(index, 1)
	}
}

export function getNotifications() {
	return notifications
}

Qualquer componente em qualquer lugar pode disparar uma notificação:

<!-- DeepNestedComponent.svelte -->
<script>
	import { addNotification } from '$lib/stores/notifications.svelte.js'

	function handleSave() {
		// ... save logic
		addNotification('Saved successfully!', 'success')
	}
</script>

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

E um único componente de UI os renderiza todos:

<!-- NotificationToast.svelte -->
<script>
	import { getNotifications, removeNotification } from '$lib/stores/notifications.svelte.js'

	const notifications = getNotifications()
</script>

<div class="toast-container">
	{#each notifications as notification (notification.id)}
		<div class="toast {notification.type}">
			{notification.message}
			<button onclick={() => removeNotification(notification.id)}>×</button>
		</div>
	{/each}
</div>

Context seria inadequado aqui — o disparador de notificação e o componente de exibição podem estar em partes completamente diferentes da árvore, sem um ancestral comum.

Pontos fortes dos stores:

Verdadeiramente global — Mesma instância em todos os lugares, sem necessidade de providers
Funciona em qualquer lugar — Componentes, utilitários e clientes de API têm acesso
Persistente — Os dados sobrevivem à desmontagem de componentes e à navegação
Simples — Basta importar e usar, sem cerimônia

Quando Context Supera os Stores

Context vence quando partes diferentes da aplicação precisam de valores diferentes:

<!-- Different cart contexts for different vendors -->
<MarketplacePage>
	<!-- Vendor A's section with its own cart -->
	<CartProvider storageKey="vendor-a-cart" taxRate={0.08}>
		<VendorAProducts />
		<VendorACart />
	</CartProvider>

	<!-- Vendor B's section with its own cart -->
	<CartProvider storageKey="vendor-b-cart" taxRate={0.1}>
		<VendorBProducts />
		<VendorBCart />
	</CartProvider>
</MarketplacePage>

Um carrinho baseado em store forçaria todos os vendedores a compartilhar um único carrinho. Context permite isolamento completo por subárvore.

Pontos fortes do context:

Seguro para SSR — Cada requisição recebe um context novo automaticamente
Escopo por subárvore — Diferentes providers podem coexistir com valores diferentes
Propriedade clara — O componente provider é dono do ciclo de vida do estado
Testável — Envolva com um provider mock para testes

O Problema do SSR com Stores

Stores em nível de módulo são perigosos em ambientes SSR. No SvelteKit, a renderização no lado do servidor compartilha o escopo do módulo entre todas as requisições. Isso significa que um store definido em nível de módulo é compartilhado entre todos os usuários, levando a vazamentos de dados e vulnerabilidades de segurança.

// ❌ DANGEROUS: Shared across all users on server
// src/lib/stores/user.svelte.ts
let currentUser = $state<User | null>(null)

export function setUser(user: User) {
	currentUser = user // User A sets this...
}

export function getUser() {
	return currentUser // ...User B sees User A's data!
}

A requisição A define currentUser como Alice. Antes de a resposta ser concluída, a requisição B chega e lê currentUser — obtendo os dados de Alice em vez dos de Bob.

Aqui está uma representação visual do perigo no SSR:

Padrões Seguros de Stores para SSR

Se você precisar de stores com SSR, há padrões seguros a seguir. Você pode combinar context e funções factory para criar instâncias de store por requisição. E como o Context está vinculado a instâncias de componentes, que são criadas de forma nova para cada requisição, não há risco de vazamento de dados entre requisições.

// Option 1: Factory function + context (best of both worlds)
// src/lib/user/context.ts
import { getContext, setContext } from 'svelte'

const USER_KEY = Symbol('user')

export function createUserStore() {
	let user = $state<User | null>(null)

	return {
		get user() {
			return user
		},
		setUser(u: User) {
			user = u
		},
		clear() {
			user = null
		}
	}
}

export function setUserContext(store: ReturnType<typeof createUserStore>) {
	setContext(USER_KEY, store)
}

export function getUserContext() {
	return getContext<ReturnType<typeof createUserStore>>(USER_KEY)
}

<!-- +layout.svelte -->
<script>
	import { createUserStore, setUserContext } from '$lib/user/context.js'

	let { data, children } = $props()

	// Fresh store per request (SSR-safe)
	const userStore = createUserStore()
	userStore.setUser(data.user)
	setUserContext(userStore)
</script>

{@render children()}

Isso oferece a ergonomia dos stores com a segurança de SSR do context.

Lembre-se: Context é inerentemente seguro para SSR porque cada requisição obtém sua própria árvore de componentes e, portanto, suas próprias instâncias de context. Isso torna o context a escolha ideal para estado por requisição em aplicações SSR.

Combinando Stores e Context

Para aplicações SSR que precisam de estado persistente no lado do cliente:

<!-- CartProvider.svelte -->
<script>
	import { setContext } from 'svelte'
	import { browser } from '$app/environment'

	let { children } = $props()

	// SSR-safe initialization
	let items = $state<CartItem[]>([])

	// Hydrate from localStorage on client only
	$effect(() => {
		if (browser) {
			const saved = localStorage.getItem('cart')
			if (saved) {
				const parsed = JSON.parse(saved)
				items.length = 0
				items.push(...parsed)
			}
		}
	})

	// Persist changes on client only
	$effect(() => {
		if (browser && items.length > 0) {
			localStorage.setItem('cart', JSON.stringify(items))
		}
	})

	setContext('cart', {
		get items() {
			return items
		},
		get total() {
			return items.reduce((sum, i) => sum + i.price * i.quantity, 0)
		},
		addItem(product: Product, quantity = 1) {
			const existing = items.find((i) => i.productId === product.id)
			if (existing) {
				existing.quantity += quantity
			} else {
				items.push({
					productId: product.id,
					name: product.name,
					price: product.price,
					quantity
				})
			}
		},
		clear() {
			items.length = 0
			if (browser) {
				localStorage.removeItem('cart')
			}
		}
	})
</script>

{@render children()}

Isso oferece segurança para SSR com persistência no lado do cliente — o melhor dos dois mundos.

Orientação de Decisão: Context vs Stores

Cenário	Melhor Escolha	Raciocínio
Aplicação SSR	Context	O isolamento por requisição é automático
Estado somente no cliente	Qualquer um	Sem preocupações com SSR
Valores diferentes por subárvore	Context	O sombreamento de context permite isso
Mesmo valor em todos os lugares	Store	Mais simples, sem necessidade de providers
Acesso fora de componentes necessário	Store	Funciona em utilitários e clientes de API
Dados sobrevivem à navegação	Store	Persiste entre desmontagens de componentes
Componentes testáveis	Context	Mock fácil via providers
Bibliotecas externas precisam de acesso	Store	Pode importar diretamente sem context

Context vs Estado de Módulo

Estado em nível de módulo é a forma mais simples de estado compartilhado: uma variável exportada de um módulo. Entender a diferença entre isso e context é crucial para evitar bugs em produção.

A Diferença Central

Estado de módulo é global por definição — todo importador compartilha a mesma variável. Context cria instâncias isoladas por provider.

// Module state: one value, period
// counter.svelte.ts
let count = $state(0)

export function getCount() {
	return count
}
export function increment() {
	count++
}

// Context: one value per provider
// In ComponentA: setContext('counter', createCounter())
// In ComponentB: setContext('counter', createCounter())
// ComponentA's children get a different counter than ComponentB's

Quando o Estado de Módulo Faz Sentido

Estado de módulo funciona para preocupações verdadeiramente singleton que:

São idênticas para todos os usuários
Não precisam de isolamento para SSR
Nunca variam pela localização na árvore

// src/lib/config.ts
// Configuration loaded once at startup, never changes per-user
export const features = {
	enableNewCheckout: import.meta.env.VITE_ENABLE_NEW_CHECKOUT === 'true',
	showBetaBanner: import.meta.env.VITE_SHOW_BETA_BANNER === 'true',
	maxUploadSize: 10 * 1024 * 1024
}

// src/lib/analytics.ts
// Side-effect system, doesn't hold user state
export function trackEvent(name: string, properties?: Record<string, unknown>) {
	fetch('/api/analytics', {
		method: 'POST',
		body: JSON.stringify({ name, properties, timestamp: Date.now() })
	})
}

export function trackPageView(path: string) {
	trackEvent('page_view', { path })
}

Esses são genuinamente singleton — os mesmos para todo usuário, toda requisição.

Por Que o Estado de Módulo Falha para Dados do Usuário

Este padrão destrói sua aplicação em produção:

// ❌ NEVER DO THIS
// src/lib/stores/auth.ts
let currentUser = $state<User | null>(null)

export function login(user: User) {
	currentUser = user
}

export function logout() {
	currentUser = null
}

export function getCurrentUser() {
	return currentUser
}

No servidor:

A requisição A faz login como Alice, define currentUser = alice
A requisição B chega, chama getCurrentUser(), obtém... Alice
A requisição B renderiza os dados de Alice para um usuário completamente diferente

Isso não é uma preocupação teórica — é um incidente de produção esperando para acontecer.

A Alternativa com Context

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

const AUTH_KEY = Symbol('auth')

export function createAuthContext() {
	let user = $state<User | null>(null)
	let loading = $state(true)

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

		setUser(u: User | null) {
			user = u
			loading = false
		},
		logout() {
			user = null
		}
	}
}

export function setAuthContext(ctx: ReturnType<typeof createAuthContext>) {
	setContext(AUTH_KEY, ctx)
}

export function getAuthContext() {
	return getContext<ReturnType<typeof createAuthContext>>(AUTH_KEY)
}

Cada requisição cria seu próprio context de autenticação. Nenhuma contaminação cruzada é possível.

Orientação de Decisão: Context vs Estado de Módulo

Cenário	Melhor Escolha	Raciocínio
Dado é verdadeiramente singleton (igual para todos)	Estado de módulo	Simples e apropriado
Configuração estática ou constantes	Estado de módulo	Nunca muda, sem necessidade de isolamento
Aplicações somente no cliente	Qualquer um	Sem preocupações com SSR
Sistemas de efeitos colaterais (analytics, logging)	Estado de módulo	Nenhum estado de usuário envolvido
Dados variam por usuário ou requisição	Context	O isolamento é essencial
Partes diferentes da aplicação precisam de valores diferentes	Context	Estado de módulo não consegue fornecer isso
Aplicações SSR com dados do usuário	Context	A segurança no SSR não é negociável
Testes requerem isolamento	Context	Fácil de fornecer context mock

Context vs Eventos e Props Bindable

Eventos e props bindable lidam com padrões de comunicação diferentes do context. Entender quando usar cada um completa seu conjunto de ferramentas de comunicação entre componentes.

Eventos: Comunicação do Filho para o Pai

No Svelte 5, eventos são implementados como callback props:

<!-- Child.svelte -->
<script lang="ts">
	interface Props {
		onselect?: (item: Item) => void
	}

	let { onselect }: Props = $props()

	function handleClick(item: Item) {
		onselect?.(item)
	}
</script>

<button onclick={() => handleClick({ id: 1, name: 'Item' })}>
	Select
</button>

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

	function handleSelect(item) {
		console.log('Selected:', item)
	}
</script>

<Child onselect={handleSelect} />

Context para Comunicação Ascendente Profunda

Para comunicação que precisa pular níveis no sentido ascendente, coloque callbacks no context:

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

	let { onsubmit, children } = $props()

	let fields = $state<Record<string, unknown>>({})
	let errors = $state<Record<string, string>>({})

	function validate() {
		// validation logic
		return Object.keys(errors).length === 0
	}

	setContext('form', {
		get fields() {
			return fields
		},
		get errors() {
			return errors
		},

		setField(name: string, value: unknown) {
			fields[name] = value
		},

		setError(name: string, error: string) {
			errors[name] = error
		},

		submit() {
			if (validate()) {
				onsubmit?.(fields)
			}
		}
	})
</script>

{@render children()}

<!-- DeepInput.svelte (many levels deep) -->
<script>
	import { getContext } from 'svelte'

	let { name, label } = $props()
	const form = getContext('form')
</script>

<label>
	{label}
	<input
		value={form.fields[name] ?? ''}
		oninput={(e) => form.setField(name, e.target.value)}
	/>
	{#if form.errors[name]}
		<span class="error">{form.errors[name]}</span>
	{/if}
</label>

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

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

<button onclick={form.submit}>Submit</button>

O provedor de formulário expõe um método submit no context, que internamente chama o callback prop onsubmit. Isso conecta o fluxo descendente do context com a notificação ascendente para o componente pai.

Props Bindable: Binding Bidirecional

Props bindable ($bindable) habilitam binding bidirecional entre pai e filho:

<!-- ColorPicker.svelte -->
<script lang="ts">
	let { color = $bindable('#000000') } = $props()
</script>

<input type="color" bind:value={color} />

<!-- Parent.svelte -->
<script>
	import ColorPicker from './ColorPicker.svelte'

	let selectedColor = $state('#ff0000')
</script>

<ColorPicker bind:color={selectedColor} />
<p>Selected: {selectedColor}</p>

Alterações em qualquer direção se propagam automaticamente.

Resumo dos Padrões de Comunicação

Padrões de Comunicação (Arte ASCII)

Props: Parent → Child
[Parent] --data--> [Child]

Events: Child → Parent
[Child] --callback--> [Parent]

Bindable: Bidirectional
[Parent] <==bind:value==> [Child]

Context Callback: Deep → Ancestor
[Ancestor: setContext with callback]
^
|
[Deep Descendant: calls context.submit()]
|
v
[Ancestor: callback triggered]

Orientação de Decisão: Padrões de Comunicação

Necessidade	Melhor Abordagem
Pai fornece dados ao filho	Props
Filho notifica pai de uma ação	Evento (callback prop)
Binding bidirecional simples	Props bindable
Descendente profundo aciona ancestral	Context com callback
Estado complexo de formulário	Context (padrão de form)
Input de formulário simples pai-filho	Props bindable

Context vs Funções Load do SvelteKit

As funções load do SvelteKit buscam dados no servidor. O Context os compartilha com os componentes. Eles são complementares, não concorrentes.

Fundamentos do Load no SvelteKit

// +page.server.ts
import type { PageServerLoad } from './$types'

export const load: PageServerLoad = async ({ locals }) => {
	const user = await getUser(locals.session)
	const posts = await getPosts(user.id)

	return { user, posts }
}

<!-- +page.svelte -->
<script>
	let { data } = $props()
	// data.user, data.posts available via props
</script>

<h1>Welcome, {data.user.name}</h1>

Os dados do load chegam via prop data. Este é o padrão padrão para dados no nível de rota.

Context para Acesso Profundo

Quando descendentes profundos precisam de dados do load sem prop drilling:

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

	let { data, children } = $props()

	// Make user available to all descendants
	setContext('user', {
		get current() {
			return data.user
		},
		get permissions() {
			return data.user.permissions
		}
	})
</script>

{@render children()}

<!-- src/lib/components/UserBadge.svelte (used anywhere) -->
<script>
	import { getContext } from 'svelte'

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

<span class="badge">{user.current.name}</span>

Arquitetura do Fluxo de Dados

Orientação de Decisão: Load vs Context

Necessidade	Melhor Abordagem
Buscar dados do servidor	SvelteKit load
Dados específicos de rota	SvelteKit load → props
Compartilhar dados do load em profundidade	Load → Context
Estado de autenticação	`hooks.server.ts` + load → Context
Estado somente no lado cliente	Context ou stores
Estado global de UI (notificações)	Context

Por Que Bibliotecas Externas Raramente São Necessárias

As ferramentas nativas do Svelte 5—$state, $derived, $effect e context—lidam com praticamente todas as necessidades de gerenciamento de estado de forma elegante. Ao contrário de alguns outros frameworks, o sistema de reatividade do Svelte é abrangente o suficiente para que bibliotecas externas de gerenciamento de estado adicionem complexidade sem benefício significativo para a grande maioria das aplicações.

O Conjunto Completo de Ferramentas do Svelte 5

Necessidade de Gerenciamento de Estado	Solução no Svelte 5
Estado com escopo de componente	`$state`
Valores computados	`$derived`
Efeitos colaterais	`$effect`
Estado compartilhado com escopo de árvore	Context API
Estado global compartilhado	`$state` em nível de módulo em arquivos `.svelte.ts`
Estado compartilhado seguro para SSR	Context com funções factory
Estado de formulário	Context (padrão de form)
Tema/Auth/Locale	Context
Busca de dados	Funções `load` do SvelteKit
Globais somente no cliente	`$state` em nível de módulo (com consciência de SSR)

O Padrão Prático

A maioria das aplicações não precisa de nada além disso:

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

	let { children } = $props()

	let items = $state([])
	let loading = $state(false)
	let error = $state(null)

	setContext('data', {
		get items() {
			return items
		},
		get loading() {
			return loading
		},
		get error() {
			return error
		},
		async load() {
			loading = true
			error = null
			try {
				const response = await fetch('/api/items')
				items = await response.json()
			} catch (e) {
				error = e instanceof Error ? e : new Error(String(e))
			} finally {
				loading = false
			}
		}
	})
</script>

{@render children()}

Este padrão fornece estados de carregamento, tratamento de erros e dados reativos—tudo com zero dependências externas.

Adicionando Cache Quando Necessário

Se você precisar de cache simples, estenda o padrão:

// lib/context/users.svelte.ts
export class UsersContext {
	#users = $state<User[]>([])
	#loading = $state(false)
	#error = $state<Error | null>(null)
	#lastFetched = $state<number>(0)
	#cacheTime = 5 * 60 * 1000 // 5 minutes

	get users() {
		return this.#users
	}
	get isLoading() {
		return this.#loading
	}
	get error() {
		return this.#error
	}

	async load(forceRefresh = false) {
		// Return cached data if fresh
		const isCacheValid = Date.now() - this.#lastFetched < this.#cacheTime
		if (!forceRefresh && isCacheValid && this.#users.length > 0) {
			return
		}

		this.#loading = true
		this.#error = null

		try {
			const response = await fetch('/api/users')
			this.#users = await response.json()
			this.#lastFetched = Date.now()
		} catch (e) {
			this.#error = e instanceof Error ? e : new Error(String(e))
		} finally {
			this.#loading = false
		}
	}

	invalidate() {
		this.#lastFetched = 0
	}
}

Isso fornece cache baseado em tempo, atualização forçada e invalidação de cache—padrões que cobrem a maioria das necessidades do mundo real sem dependências externas.

A Conclusão

Comece com os recursos nativos do Svelte. Eles foram projetados para trabalhar juntos de forma integrada e lidar com as necessidades de gerenciamento de estado da maioria das aplicações de forma elegante. A reatividade baseada em runes do Svelte 5 combinada com a Context API é notavelmente poderosa.

As raras exceções onde ferramentas externas podem ajudar envolvem requisitos altamente especializados, como máquinas de estado finito complexas ou edição colaborativa em tempo real—cenários que a maioria das aplicações jamais encontra.

Em caso de dúvida, construa com os padrões nativos do Svelte primeiro. Você descobrirá que eles levam você mais longe do que poderia esperar.

Padrões Híbridos: Combinando Abordagens

Aplicações reais frequentemente combinam múltiplos padrões de forma estratégica. Veja como eles funcionam juntos.

Context Fornecendo Acesso Similar a Store

Combine o isolamento do context com a ergonomia similar a stores:

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

const CART_KEY = Symbol('cart')

export function createCartStore() {
	let items = $state<CartItem[]>([])

	const subtotal = $derived(items.reduce((sum, item) => sum + item.price * item.quantity, 0))

	return {
		get items() {
			return items
		},
		get subtotal() {
			return subtotal
		},
		get itemCount() {
			return items.length
		},

		addItem(product: Product, quantity = 1) {
			const existing = items.find((i) => i.productId === product.id)
			if (existing) {
				existing.quantity += quantity
			} else {
				items.push({
					productId: product.id,
					name: product.name,
					price: product.price,
					quantity
				})
			}
		},

		removeItem(productId: string) {
			const index = items.findIndex((i) => i.productId === productId)
			if (index !== -1) {
				items.splice(index, 1)
			}
		},

		clear() {
			items.length = 0
		}
	}
}

export type CartStore = ReturnType<typeof createCartStore>

export function setCartContext(store: CartStore) {
	setContext(CART_KEY, store)
}

export function getCartContext(): CartStore {
	return getContext<CartStore>(CART_KEY)
}

Isso oferece:

Isolamento de context: Cada provedor cria seu próprio carrinho (seguro para SSR)
Ergonomia de store: Padrão simples de importação e uso
Segurança de tipos: Suporte completo a TypeScript
Testabilidade: Fácil de fornecer implementações mock

Props para Configuração, Context para Tempo de Execução

<!-- CartProvider.svelte -->
<script lang="ts">
	import { setCartContext, createCartStore } from './context.js'
	import { browser } from '$app/environment'

	interface Props {
		taxRate?: number
		currency?: string
		persistKey?: string
		children: import('svelte').Snippet
	}

	let { taxRate = 0.0, currency = 'USD', persistKey, children }: Props = $props()

	// Runtime state via context
	const cart = createCartStore()
	setCartContext(cart)

	// Persistence effect if key provided
	$effect(() => {
		if (persistKey && browser) {
			localStorage.setItem(persistKey, JSON.stringify(cart.items))
		}
	})
</script>

{@render children()}

Props configuram o provedor (estático). Context fornece o estado em tempo de execução (dinâmico).

Constantes de Módulo + Estado de Context

// src/lib/config.ts
// Static configuration as module constants (safe)
export const API_BASE = import.meta.env.VITE_API_URL
export const APP_NAME = 'MyApp'
export const MAX_UPLOAD_SIZE = 10 * 1024 * 1024

// src/lib/user/context.ts
// Dynamic, per-request state as context (isolated)
import { API_BASE } from '$lib/config.js'

export function createUserContext(initialUser: User | null) {
	let user = $state(initialUser)

	return {
		get user() {
			return user
		},

		async refresh() {
			const response = await fetch(`${API_BASE}/me`)
			user = await response.json()
		}
	}
}

Constantes de módulo para configuração estática. Context para estado dinâmico e específico do usuário. Cada um utilizado onde for apropriado.

O Framework de Decisão

Use este fluxograma para escolher a abordagem certa para qualquer necessidade de gerenciamento de estado:

Matriz de Comparação

Referência rápida para seleção de padrões:

Feature	Props	Context	Stores	Events	Module State
Direction	Parent→Child	Ancestor→Descendant	Anywhere	Child→Parent	Anywhere
Explicit deps	✅ Best	❌ Implicit	❌ Implicit	✅ Best	❌ Implicit
Type safety	✅ Best	⚠️ Good	⚠️ Good	✅ Best	⚠️ Good
Prop drilling	❌ Required	✅ Avoided	✅ Avoided	❌ Required	✅ Avoided
Subtree scoping	❌ No	✅ Yes	❌ No	N/A	❌ No
SSR safe	✅ Always	✅ Always	⚠️ Careful	✅ Always	❌ Dangerous
Non-component access	❌ No	❌ No	✅ Yes	❌ No	✅ Yes
Testability	✅ Best	⚠️ Good	⚠️ Varies	✅ Best	❌ Hard
Survives unmount	N/A	❌ No	✅ Yes	N/A	✅ Yes
IDE support	✅ Best	⚠️ Good	⚠️ Good	✅ Best	⚠️ Good

Cenários do Mundo Real

Aplicação de E-commerce

Estado	Padrão	Justificativa
Autenticação do usuário	Load → Context	Seguro para SSR, compartilhado profundamente em toda a aplicação
Carrinho de compras	Context	Seguro para SSR, diferentes carrinhos por seção são possíveis
Lista de produtos	Load → Props	Específico por rota, API de componente explícita
Tema	Context	Tematização por subárvore é possível
Notificações toast	Context	Componente de UI renderiza, acionado em qualquer lugar
Configuração de analytics	Module state	Verdadeiramente global, sem dados do usuário

Aplicação de Dashboard

Estado	Padrão	Justificativa
Auth/permissões	Load → Context	Seguro para SSR, verificado em qualquer lugar
Workspace selecionado	Context	Diferente por seção de rota
Dados de widget	Load por widget	Baseado em rota, isolado
Preferências do usuário	Context	Aplicação por subárvore
Atualizações em tempo real	Store (client-only)	Handler de WebSocket precisa de acesso

Aplicação com Muitos Formulários

Estado	Padrão	Justificativa
Valores do formulário	Context	Muitos inputs, gerenciamento centralizado
Erros de validação	Context	Compartilhado com todos os campos
Estado em nível de campo	$state	Local ao componente
Handler de submit	Context callback	Chamado a partir de botão de submit profundo
Rastreamento de alterações	$derived in context	Computado a partir dos campos

Erros Comuns e Anti-Padrões

Erro 1: Escolher pelo familiar, não pelo adequado

Não use stores em todo lugar porque você está confortável com eles. Não use context para tudo porque leu esta série. Combine o padrão com o problema.

Erro 2: Estado de módulo com dados do usuário

// ❌ This will cause cross-request data leaks in SSR
let currentUser = $state(null)

Se os dados variam por usuário, não podem estar em nível de módulo em aplicações SSR.

Erro 3: Context para relacionamento direto pai-filho

<!-- ❌ Over-engineered -->
<Parent>
	<!-- setContext -->
	<Child />
	<!-- getContext -->
</Parent>

Props são mais simples, mais claros e melhor tipados para relacionamentos diretos.

Erro 4: Stores para dados com escopo de subárvore

// ❌ Can't have different themes in different sections
// src/lib/theme.ts
let theme = $state('light')

Estado em nível de módulo é global. Se partes diferentes da aplicação precisam de valores diferentes, use context.

Erro 5: Props por 5+ níveis

<!-- ❌ Prop drilling pain -->
<A {data}>
	<B {data}>
		<C {data}>
			<D {data}>
				<E {data} />
			</D>
		</C>
	</B>
</A>

Context elimina esse acoplamento. Não torture seus componentes intermediários.

Erro 6: Ignorar considerações de SSR

// ❌ Works in dev, breaks in production
export let globalState = $state({ user: null })

Sempre considere a segurança de SSR ao escolher padrões para estado compartilhado.

Referência Rápida para Seleção de Padrões

Use esta matriz para decisões rápidas:

Cenário	Padrão Recomendado
Dados diretos pai → filho	Props
Pular 2+ níveis	Context
Dados ambientes (tema, auth, locale)	Context
Componentes compostos (Tabs/Tab)	Context
Valores diferentes em subárvores diferentes	Context
Singleton verdadeiramente global (igual para todos os usuários)	Module state
Estado global somente no cliente	Store (com cautela)
Aplicação SSR com dados do usuário	Context
Comunicação entre irmãos	Elevar estado + props
Comunicação entre árvores (notificações)	Store (client-only) ou Context (SSR)
Configuração estática	Constantes de módulo
Filho notifica pai	Events (callback props)
Binding bidirecional pai-filho	Bindable props
Dados de rota obtidos do servidor	SvelteKit Load
Acesso profundo a dados de load	Load → Context

Conclusão

A questão não é qual padrão é melhor — é qual padrão se encaixa em cada situação. Cada abordagem de gerenciamento de estado no Svelte 5 se destaca em cenários específicos:

Props fornecem comunicação pai-filho explícita e com tipagem segura. Eles são a base das APIs de componentes e devem ser sua escolha padrão para relacionamentos diretos.

Context brilha quando você precisa pular componentes intermediários ou restringir valores diferentes a subárvores diferentes. É seguro para SSR por design e perfeito para dados ambientes como temas, autenticação e configuração.

Stores funcionam para estado verdadeiramente global que código fora de componentes precisa acessar. Use-os com cuidado em aplicações SSR, preferindo o padrão de factory encapsulado em context.

Events (callback props) comunicam para cima, de filhos para pais. Combine-os com context para padrões de comunicação de componentes profundos para ancestrais.

Module state é apropriado apenas para singletons genuínos que não variam por usuário ou requisição. Nunca o utilize para dados específicos do usuário em aplicações SSR.

SvelteKit Load busca dados de rota no servidor. Combine-o com context para compartilhar esses dados profundamente sem prop drilling.

As aplicações mais fáceis de manter usam múltiplos padrões em combinação, escolhendo a ferramenta certa para cada trabalho. Comece de forma simples com $state e props, depois recorra ao context quando encontrar prop drilling. Reserve stores para estado verdadeiramente global no lado do cliente, e sempre considere a segurança de SSR nas suas decisões de arquitetura.

Principais Conclusões

Props — Melhor para pai-filho direto, APIs explícitas, máxima segurança de tipos. Escolha padrão para 1-2 níveis.

Context — Melhor para pular níveis, escopo de subárvore, segurança de SSR e estado interno de componentes compostos. Use quando props percorrem 3+ níveis.

Stores — Melhor para estado verdadeiramente global, acesso fora de componentes e dados que sobrevivem a desmontagens. Tenha cuidado com SSR.

Events — Melhor para notificação de filho para pai. Combine com callbacks de context para comunicação profunda.

Module State — Apenas para singletons genuínos (configuração, analytics). Nunca para dados do usuário em aplicações SSR.

SvelteKit Load — Melhor para dados de rota obtidos do servidor. Combine com context para acesso profundo.

As melhores aplicações combinam abordagens: carregue dados com SvelteKit, compartilhe-os profundamente com context, use props para APIs de componentes explícitas, events para ações de filho para pai, e reserve stores para estado verdadeiramente global sem SSR.

O Que Vem a Seguir

Coloque o contexto em prática com Gerenciamento de Temas com Context, construindo um sistema de temas completo com modos claro/escuro, detecção de preferência do sistema e propriedades personalizadas CSS.

Veja Também

Documentação Oficial

Svelte Context — Guia oficial
Svelte Stores — Documentação de stores
SvelteKit Load — Carregamento de dados

Muitos Mecanismos, Uma Decisão

O Panorama do Gerenciamento de Estado

Visão Geral dos Padrões

Arquitetura Visual

Entendendo os Modelos Mentais

Direções do Fluxo de Dados

Visualização de Escopo

Context vs Props

A Diferença Central

Quando Props se Destacam

Quando Context Vence

Resumo dos Trade-offs

Exemplo Lado a Lado: Dados de Tema

A Abordagem Híbrida

Guia de Decisão: Props vs Context

Context vs Stores

A Diferença Central

Quando Stores se Destacam

Quando Context Supera os Stores

O Problema do SSR com Stores

Padrões Seguros de Stores para SSR

Combinando Stores e Context

Orientação de Decisão: Context vs Stores

Context vs Estado de Módulo

A Diferença Central

Quando o Estado de Módulo Faz Sentido

Por Que o Estado de Módulo Falha para Dados do Usuário

A Alternativa com Context

Orientação de Decisão: Context vs Estado de Módulo

Context vs Eventos e Props Bindable

Eventos: Comunicação do Filho para o Pai

Context para Comunicação Ascendente Profunda

Props Bindable: Binding Bidirecional

Resumo dos Padrões de Comunicação

Orientação de Decisão: Padrões de Comunicação

Context vs Funções Load do SvelteKit

Fundamentos do Load no SvelteKit

Context para Acesso Profundo

Arquitetura do Fluxo de Dados

Orientação de Decisão: Load vs Context

Por Que Bibliotecas Externas Raramente São Necessárias

O Conjunto Completo de Ferramentas do Svelte 5

O Padrão Prático

Adicionando Cache Quando Necessário

A Conclusão

Padrões Híbridos: Combinando Abordagens

Context Fornecendo Acesso Similar a Store

Props para Configuração, Context para Tempo de Execução

Constantes de Módulo + Estado de Context

O Framework de Decisão

Matriz de Comparação

Cenários do Mundo Real

Aplicação de E-commerce

Aplicação de Dashboard

Aplicação com Muitos Formulários

Erros Comuns e Anti-Padrões

Erro 1: Escolher pelo familiar, não pelo adequado

Erro 2: Estado de módulo com dados do usuário

Erro 3: Context para relacionamento direto pai-filho

Erro 4: Stores para dados com escopo de subárvore

Erro 5: Props por 5+ níveis

Erro 6: Ignorar considerações de SSR

Referência Rápida para Seleção de Padrões

Conclusão

Principais Conclusões

O Que Vem a Seguir

Veja Também

Documentação Oficial

Artigos Relacionados