Muitos Mecanismos, Uma Decisão

O Svelte oferece 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 um é "melhor", compreender 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 se destaca. Seja você construindo sua primeira aplicação Svelte ou arquitetando um sistema complexo de 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 se manter com props simples e quando pode ser necessário 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. Compreender 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	Descendente (um nível)	Automática	✅ Seguro
Context	Ancestral → qualquer descendente	Descendente (múltiplos níveis)	Manual ($state)	✅ Seguro
Stores	Em qualquer lugar no escopo do módulo	Qualquer direção	Embutida	⚠️ Requer cuidado
Eventos	Filho → pai	Ascendente (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.

Compreendendo os Modelos Mentais

Antes de comparar os padrões, vamos entender como cada um move dados conceitualmente 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 exige que os dados sejam encaminhados por cada componente intermediário.

Context cria um canal implícito de qualquer ancestral para qualquer descendente. Os componentes intermediários não precisam saber sobre os dados nem encaminhá-los. Isso resolve o prop drilling, mas introduz dependências ocultas.

Eventos (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 importe um store compartilha o mesmo estado reativo, possibilitando padrões impossíveis com comunicação restrita à árvore.

Visualização de Escopo

Compreender o escopo é fundamental, 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 de 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 recorrer ao 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, cada componente intermediário precisa lidar com os dados (amarelo). Com context, os intermediários são completamente alheios (cinza).

Quando Props se Destacam

Props vencem 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 vasculhar componentes ancestrais.

Pontos fortes das props:

Explícitas — Você vê exatamente quais dados um componente precisa ao ler suas props
Type-safe — Suporte completo ao TypeScript com autocomplete e verificação de erros na IDE
Descobríveis — As props aparecem nas assinaturas dos componentes, tornando as APIs autodocumentadas
Testáveis — Fácil de fornecer diferentes props em testes sem precisar mockar context
Refatoráveis — Renomeie uma prop e o TypeScript mostrará 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 permanecem limpos e focados
Desacoplados — Componentes só declaram 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 constam na assinatura do componente
Overhead de testes — Necessita de 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 os providers
Reusabilidade	✔ Sem dependência de context	✘ Acoplado à estrutura do context
Componentes intermediários	✘ Devem passar por todos	✔ Pula intermediários
Acoplamento	✘ Intermediários acoplados aos dados	✔ Reduz o acoplamento
Dados ambiente	⚠️ Verboso para tema/auth/locale	✔ Melhor encaixe

Guia de Melhor Escolha:

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 ambiente de Tema/Auth/Locale

Exemplo Lado a Lado: Dados de Tema

Vamos ver 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 de 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 para este card) chegam via props. Preocupações transversais (carrinho, tema) chegam via context. Essa separação mantém a API principal do componente explícita enquanto evita prop drilling para dados ambiente.

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

Cenário	Melhor Escolha	Raciocínio
Pai-filho direto	Props	Claro, explícito, totalmente tipado
1-2 níveis de profundidade	Props	O overhead do drilling é gerenciável
3+ níveis de profundidade	Context	Evitar acoplamento de componentes intermediários
API pública de biblioteca de componentes	Props	Consumidores precisam de interface explícita e documentada
Estado interno de componente composto	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 exigida	Props	Melhor suporte de IDE e refatoração
Tema, auth, locale	Context	Dados ambiente usados por toda a subárvore

Context vs Stores

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

A Diferença Principal

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

Com context, a Subárvore B pode sobrepor 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 todo lugar:

// 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 renderiza todas elas:

<!-- 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 a exibição podem estar em partes completamente diferentes da árvore sem nenhum ancestral comum.

Pontos fortes dos stores:

Verdadeiramente global — Mesma instância em todo lugar, sem providers necessários
Funciona em qualquer lugar — Componentes, utilitários, clientes de API têm acesso
Persiste — Os dados sobrevivem a desmontagens de componentes e navegações
Simples — Basta importar e usar, sem cerimônia

Quando Context Vence 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 context fresco automaticamente
Escopo de 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 no 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 que a resposta seja 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 Store para SSR

Se você precisar de stores com SSR, existem 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 é vinculado a instâncias de componentes, que são criadas do zero 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 ergonomia semelhante a stores com a segurança SSR do context.

Lembre-se: Context é inerentemente seguro para SSR porque cada requisição recebe sua própria árvore de componentes e, portanto, suas próprias instâncias de context. Isso torna o context a escolha preferida 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 SSR com persistência no lado do cliente — o melhor dos dois mundos.

Guia 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 todo lugar	Store	Mais simples, sem providers necessários
Acesso fora de componentes necessário	Store	Funciona em utilitários, clientes de API
Dados sobrevivem à navegação	Store	Persiste entre desmontagens de componentes
Componentes testáveis	Context	Mock via providers facilmente
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 Principal

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 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 SSR
Nunca variam por 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 Estado de Módulo Falha para Dados de 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.

Guia 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 com efeitos colaterais (analytics, logs)	Estado de módulo	Nenhum estado de usuário envolvido
Dados variam por usuário ou requisição	Context	Isolamento é essencial
Partes diferentes precisam de valores diferentes	Context	Estado de módulo não consegue fornecer isso
Aplicações SSR com dados de usuário	Context	Segurança SSR não é negociável
Testes requerem isolamento	Context	Fácil de fornecer context mock

Contexto vs Eventos e Props Vinculáveis

Eventos e props vinculáveis lidam com padrões de comunicação diferentes do contexto. 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 props de callback:

<!-- 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} />

Contexto para Comunicação Ascendente Profunda

Para comunicação que precisa pular níveis indo para cima, coloque callbacks no contexto:

<!-- 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 contexto, que internamente chama a prop de callback onsubmit. Isso faz a ponte entre o fluxo descendente do contexto e a notificação ascendente ao componente pai.

Props Vinculáveis: Vinculação Bidirecional

Props vinculáveis ($bindable) permitem vinculação 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 para Decisão: Padrões de Comunicação

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

Contexto vs Funções Load do SvelteKit

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

Noções Básicas de 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 a prop data. Este é o padrão padrão para dados no nível de rota.

Contexto 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 para Decisão: Load vs Contexto

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

Por Que Bibliotecas Externas Raramente São Necessárias

As ferramentas integradas do Svelte 5—$state, $derived, $effect e contexto—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 compartilhado global	`$state` em nível de módulo em arquivos `.svelte.ts`
Estado compartilhado seguro para SSR	Contexto com funções de fábrica
Estado de formulário	Contexto (padrão de form)
Tema/Auth/Locale	Contexto
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 disto:

<!-- 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 integrados do Svelte. Eles são projetados para funcionar juntos de forma harmoniosa e lidam 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 é extraordinariamente 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.

Na dúvida, construa com os padrões nativos do Svelte primeiro. Você descobrirá que eles te levam muito 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.

Contexto Fornecendo Acesso ao Estilo de Store

Combine o isolamento do contexto com a ergonomia estilo store:

// 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 fornece:

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

Props para Configuração, Contexto para 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 usado onde apropriado.

O Framework de Decisão

Use este fluxograma para escolher a abordagem correta 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 no app
Carrinho de compras	Context	Seguro para SSR, carrinhos diferentes 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, disparado de 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 na 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 no nível do campo	$state	Local ao componente
Handler de submit	Context callback	Chamado a partir de botão de submit aninhado
Rastreamento de alterações	$derived in context	Computado a partir dos campos

Erros Comuns e Anti-Padrões

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

Não use stores em todo lugar só porque você está confortável com eles. Não use context para tudo porque você 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 ser de nível de módulo em apps com SSR.

Erro 3: Context para relação direta pai-filho

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

Props são mais simples, mais claros e melhor tipados para relações diretas.

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 de nível de módulo é global. Se diferentes partes do app precisam de valores diferentes, use context.

Erro 5: Props através de 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 para 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)
App com SSR e dados do usuário	Context
Comunicação entre irmãos	Elevar estado + props
Comunicação entre árvores diferentes (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 do load	Load → Context

Conclusão

A questão não é qual padrão é 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 segurança de tipos. Eles são a base das APIs de componente e devem ser sua escolha padrão para relações diretas.

Context brilha quando você precisa pular componentes intermediários ou delimitar 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 encapsulada em context.

Events (callback props) comunicam-se 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 use 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 tarefa. 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 para 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 para SSR e estado interno de componentes compostos. Use quando props passam por 3+ níveis.

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

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

Module State — Apenas para singletons genuínos (config, analytics). Nunca para dados do usuário em apps com 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 componente explícitas, events para ações 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 Tema com Context, construindo um sistema de temas completo com modos claro/escuro, detecção de preferências do sistema e propriedades personalizadas de 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

Compreendendo 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

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

Context vs Stores

A Diferença Principal

Quando Stores Se Destacam

Quando Context Vence os Stores

O Problema do SSR com Stores

Padrões Seguros de Store para SSR

Combinando Stores e Context

Guia de Decisão: Context vs Stores

Context vs Estado de Módulo

A Diferença Principal

Quando Estado de Módulo Faz Sentido

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

A Alternativa com Context

Guia de Decisão: Context vs Estado de Módulo

Contexto vs Eventos e Props Vinculáveis

Eventos: Comunicação do Filho para o Pai

Contexto para Comunicação Ascendente Profunda

Props Vinculáveis: Vinculação Bidirecional

Resumo dos Padrões de Comunicação

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

Contexto vs Funções Load do SvelteKit

Noções Básicas de Load no SvelteKit

Contexto para Acesso Profundo

Arquitetura do Fluxo de Dados

Orientação para Decisão: Load vs Contexto

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

Contexto Fornecendo Acesso ao Estilo de Store

Props para Configuração, Contexto para 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 que é familiar, não pelo que é adequado

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

Erro 3: Context para relação direta pai-filho

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

Erro 5: Props através de 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