Gerenciamento de Estado Através das Fronteiras de Componentes no Svelte 5

Navegando pelas Fronteiras de Estado

O gerenciamento de estado é o coração pulsante de qualquer aplicação reativa. Ele determina como os dados fluem pelos seus componentes, como sua interface responde a mudanças e, em última análise, quão manutenível e performática sua aplicação se torna à medida que escala. O Svelte 5 reimaginou fundamentalmente o gerenciamento de estado com a introdução das runes, fornecendo aos desenvolvedores um conjunto de ferramentas mais explícito, previsível e poderoso para gerenciar estado reativo.

No Svelte 4 e versões anteriores, os desenvolvedores dependiam de uma combinação de declarações reativas ($:), stores do svelte/store e da API de Contexto para gerenciar estado em diferentes escopos. Embora essas ferramentas fossem eficazes, elas criavam um modelo mental fragmentado. O estado reativo dentro dos componentes funcionava de forma diferente do estado reativo fora dos componentes, e compartilhar estado exigia o entendimento de múltiplos paradigmas.

As runes do Svelte 5 unificam essa experiência. A rune $state funciona de forma idêntica tanto dentro de um componente quanto dentro de um módulo .svelte.js. A rune $derived substitui tanto as declarações reativas quanto as derived stores. Essa consistência significa que você pode se concentrar em entender um único conjunto de padrões que se aplica em todos os lugares, em vez de aprender abordagens diferentes para contextos diferentes.

No entanto, esse sistema unificado levanta novas questões: Quando o estado deve viver dentro de um único componente? Quando ele deve ser elevado a um módulo compartilhado? Quando a API de Contexto se torna necessária? E quando você pode querer abrir mão da reatividade profunda com $state.raw para criar stores personalizadas mais performáticas?

Este artigo irá guiá-lo por essas decisões de forma sistemática. Vamos construir um modelo mental abrangente para fronteiras de estado, explorar os trade-offs de cada abordagem e desenvolver padrões práticos que você pode aplicar imediatamente nas suas aplicações Svelte 5. Ao final, você entenderá não apenas como usar cada abordagem de gerenciamento de estado, mas por que e quando cada uma se torna a escolha ideal.

Entendendo as Fronteiras de Estado: Um Modelo Mental

Antes de mergulhar nas APIs específicas, vamos estabelecer um framework mental para pensar sobre fronteiras de estado. Cada pedaço de estado na sua aplicação existe em algum lugar em um espectro que vai de "completamente local" a "globalmente compartilhado". Entender onde um determinado pedaço de estado se encaixa nesse espectro é o primeiro passo para escolher a abordagem de gerenciamento correta.

O Espectro de Escopo de Estado

Considere o estado como existindo em quatro escopos primários, cada um com características distintas:

Estado Local de Componente representa dados que estão intrinsecamente ligados a uma única instância de componente. Pense nos valores de um input de formulário durante a edição, estado de UI como se um dropdown está aberto, ou cálculos temporários que só importam dentro do ciclo de vida daquele componente. Esse estado nasce quando o componente é montado e morre quando ele é desmontado. Não tem significado fora do seu componente.

Estado Compartilhado de Subárvore abrange dados que precisam fluir por uma parte da sua árvore de componentes sem ser explicitamente passados por cada componente intermediário. Considere um objeto de tema que toda uma seção de funcionalidade precisa acessar, ou preferências do usuário que múltiplos componentes profundamente aninhados necessitam. Esse estado tem significado além de um único componente, mas não precisa estar disponível globalmente.

Estado em Nível de Módulo refere-se a dados singleton que persistem durante o tempo de vida da sua aplicação (ou até que o módulo seja recarregado). Objetos de configuração, caches ou estado de toda a aplicação que qualquer componente possa precisar se enquadram nesta categoria. Em uma aplicação puramente client-side, isso é efetivamente um estado global.

Estado com Escopo de Requisição (particularmente relevante para aplicações SvelteKit) é o estado que deve ser isolado por requisição durante a renderização no lado do servidor. Isso é crucial em contextos SSR onde um único processo de servidor lida com múltiplos usuários—um estado que vaza entre requisições pode expor os dados de um usuário a outro.

Entender esses escopos ajuda você a tomar decisões informadas sobre onde o estado deve viver. Vamos explorar cada abordagem em detalhes.

Estado Local de Componente com `$state`

A forma mais comum e direta de gerenciamento de estado é o estado local de componente usando a rune $state. Esse é o estado que vive inteiramente dentro de uma única instância de componente, é criado quando o componente é inicializado e é removido quando o componente é destruído.

Estado Local Básico

Quando o estado é puramente local a um componente, $state fornece um mecanismo simples e poderoso para criar valores reativos:

<script>
	// Simple reactive counter - state lives entirely within this component
	let count = $state(0)

	// Complex reactive object - Svelte creates a deep reactive proxy
	let user = $state({
		name: '',
		email: '',
		preferences: {
			theme: 'light',
			notifications: true
		}
	})

	function incrementCount() {
		count++
	}

	function updateTheme(newTheme) {
		// Deep reactivity means this update triggers UI updates
		user.preferences.theme = newTheme
	}
</script>

<div>
	<p>Count: {count}</p>
	<button onclick={incrementCount}>Increment</button>

	<input bind:value={user.name} placeholder="Name" />
	<input bind:value={user.email} placeholder="Email" />

	<select bind:value={user.preferences.theme}>
		<option value="light">Light</option>
		<option value="dark">Dark</option>
	</select>
</div>

Este exemplo demonstra duas características fundamentais do $state. Primeiro, primitivos como números se tornam reativos — qualquer atribuição dispara atualizações na UI. Segundo, objetos e arrays se tornam proxies profundamente reativos, o que significa que mudanças em qualquer nível de aninhamento propagam automaticamente para a UI.

Quando o Estado Local É a Escolha Certa

O estado local é apropriado quando todas as seguintes condições são atendidas:

O estado só é significativo dentro do contexto de um único componente. Os erros de validação de um formulário, por exemplo, não têm significado fora do componente de formulário que os gera. O ciclo de vida do estado está vinculado ao ciclo de vida do componente — quando o componente é destruído, o estado deve deixar de existir. Além disso, nenhum outro componente precisa ler ou modificar esse estado diretamente.

Considere este exemplo mais completo de um componente de input de busca com estado local:

<script>
	// All of this state is purely local - no other component cares about it
	let query = $state('')
	let isFocused = $state(false)
	let suggestions = $state([])
	let selectedIndex = $state(-1)
	let isLoading = $state(false)

	// Derived state - computed from local state
	let hasSuggestions = $derived(suggestions.length > 0)
	let selectedSuggestion = $derived(selectedIndex >= 0 ? suggestions[selectedIndex] : null)

	async function fetchSuggestions(searchQuery) {
		if (searchQuery.length < 2) {
			suggestions = []
			return
		}

		isLoading = true
		try {
			const response = await fetch(`/api/suggestions?q=${encodeURIComponent(searchQuery)}`)
			suggestions = await response.json()
			selectedIndex = -1
		} finally {
			isLoading = false
		}
	}

	function handleKeydown(event) {
		if (!hasSuggestions) return

		switch (event.key) {
			case 'ArrowDown':
				event.preventDefault()
				selectedIndex = Math.min(selectedIndex + 1, suggestions.length - 1)
				break
			case 'ArrowUp':
				event.preventDefault()
				selectedIndex = Math.max(selectedIndex - 1, -1)
				break
			case 'Enter':
				if (selectedSuggestion) {
					event.preventDefault()
					query = selectedSuggestion.text
					suggestions = []
				}
				break
			case 'Escape':
				suggestions = []
				selectedIndex = -1
				break
		}
	}

	// Effect to fetch suggestions when query changes
	$effect(() => {
		const currentQuery = query
		fetchSuggestions(currentQuery)
	})
</script>

<div class="search-container">
	<input
		type="text"
		bind:value={query}
		onfocus={() => (isFocused = true)}
		onblur={() => (isFocused = false)}
		onkeydown={handleKeydown}
		placeholder="Search..."
		aria-expanded={hasSuggestions}
		aria-autocomplete="list"
	/>

	{#if isLoading}
		<span class="loading-indicator">Searching...</span>
	{/if}

	{#if hasSuggestions && isFocused}
		<ul class="suggestions" role="listbox">
			{#each suggestions as suggestion, index}
				<li
					role="option"
					aria-selected={index === selectedIndex}
					class:selected={index === selectedIndex}
					onclick={() => {
						query = suggestion.text
						suggestions = []
					}}
				>
					{suggestion.text}
				</li>
			{/each}
		</ul>
	{/if}
</div>

<style>
	.search-container {
		position: relative;
		width: 100%;
		max-width: 400px;
	}

	.suggestions {
		position: absolute;
		top: 100%;
		left: 0;
		right: 0;
		background: white;
		border: 1px solid #ccc;
		border-radius: 4px;
		margin-top: 4px;
		padding: 0;
		list-style: none;
		box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
	}

	.suggestions li {
		padding: 8px 12px;
		cursor: pointer;
	}

	.suggestions li:hover,
	.suggestions li.selected {
		background: #f0f0f0;
	}

	.loading-indicator {
		position: absolute;
		right: 10px;
		top: 50%;
		transform: translateY(-50%);
		font-size: 0.8em;
		color: #666;
	}
</style>

Cada pedaço de estado neste componente é intrinsecamente local. Os valores query, suggestions, selectedIndex, isFocused e isLoading não têm significado fora deste componente. Outros componentes podem querer saber o resultado final da busca, mas isso seria comunicado por meio de eventos ou props, e não pelo compartilhamento de estado interno.

O Erro da Elevação Prematura de Estado

Um anti-padrão comum é elevar o estado para um escopo superior "só por precaução" caso ele seja necessário em outro lugar no futuro. Isso leva a vários problemas: aumenta o acoplamento entre componentes, torna a refatoração mais difícil e pode causar problemas de desempenho à medida que mais componentes reagem a mudanças de estado que não lhes dizem respeito.

Mantenha o estado o mais local possível até que você tenha um motivo concreto para compartilhá-lo. Se você descobrir posteriormente que múltiplos componentes precisam de acesso ao mesmo estado, você pode elevá-lo naquele momento. Essa abordagem segue o princípio do menor privilégio — os componentes devem ter acesso apenas ao estado de que realmente precisam.

Compartilhando Estado Entre Módulos com Arquivos `.svelte.js`

Quando o estado precisa ser compartilhado entre componentes, mas não requer os benefícios de escopo do contexto, o estado em nível de módulo em arquivos .svelte.js ou .svelte.ts oferece uma solução elegante. Essa abordagem cria um estado singleton que persiste durante o tempo de vida da sua aplicação.

Entendendo os Arquivos `.svelte.js`

O Svelte 5 introduz uma extensão de arquivo especial — .svelte.js (ou .svelte.ts para TypeScript) — que permite usar runes fora de arquivos de componente. Isso permite que você crie lógica reativa reutilizável e módulos de estado compartilhado.

// file: counter.svelte.js

// This creates module-level reactive state - it's a singleton
// shared by all components that import this module
export const counter = $state({
	count: 0
})

export function increment() {
	counter.count++
}

export function decrement() {
	counter.count--
}

export function reset() {
	counter.count = 0
}

Qualquer componente que importar deste módulo compartilhará o mesmo estado reativo:

<!-- ComponentA.svelte -->
<script>
	import { counter, increment } from './counter.svelte.js'
</script>

<p>Count: {counter.count}</p>
<button onclick={increment}>Increment</button>

<!-- ComponentB.svelte -->
<script>
	import { counter, decrement } from './counter.svelte.js'
</script>

<p>Current value: {counter.count}</p>
<button onclick={decrement}>Decrement</button>

Ambos os componentes enxergam o mesmo objeto counter, e as mudanças feitas em um componente refletem imediatamente no outro.

A Restrição Crítica de Exportação

Há uma limitação importante a entender ao trabalhar com estado em nível de módulo: você não pode exportar diretamente uma variável de estado reatribuível. Essa limitação existe por causa de como o compilador do Svelte transforma o código baseado em runes.

Quando você escreve let count = $state(0), o compilador transforma isso em algo como:

// Conceptual transformation (simplified)
let count = $.state(0)

// When you read count:
$.get(count)

// When you write count:
$.set(count, newValue)

Essa transformação acontece por arquivo. Se você exportar count diretamente e outro arquivo o importar, esse outro arquivo não sabe como usar $.get() e $.set() — ele apenas vê um objeto de sinal bruto em vez do valor reativo.

Aqui está o que não funciona:

// file: broken.svelte.js
// ❌ This will NOT work as expected
export let count = $state(0)

export function increment() {
	count++ // This works internally
}

Quando outro arquivo importa count, ele obtém o objeto de sinal interno, não o valor numérico reativo. Acessá-lo retornaria um objeto em vez de um número.

Existem dois padrões que funcionam:

Padrão 1: Exportar um objeto com propriedades reativas

// file: counter.svelte.js
// ✅ This works - we're not reassigning counter, just its properties
export const counter = $state({
	count: 0
})

export function increment() {
	counter.count++ // Updating a property, not reassigning counter
}

Padrão 2: Exportar funções de acesso

// file: counter.svelte.js
// ✅ This also works - state is private, accessed via functions
let count = $state(0)

export function getCount() {
	return count
}

export function setCount(value) {
	count = value
}

export function increment() {
	count++
}

O primeiro padrão é geralmente mais ergonômico para a maioria dos casos de uso. O segundo padrão oferece mais encapsulamento e é útil quando você quer controlar exatamente como o estado pode ser modificado.

Construindo um Módulo de Estado Compartilhado Completo

Vamos construir um exemplo mais realista — um carrinho de compras que múltiplos componentes precisam acessar:

// file: cart.svelte.js

// The cart state - a singleton shared across the application
export const cart = $state({
	items: [],
	isOpen: false
})

// Derived values - these are also reactive
export function getItemCount() {
	return cart.items.reduce((sum, item) => sum + item.quantity, 0)
}

export function getSubtotal() {
	return cart.items.reduce((sum, item) => sum + item.price * item.quantity, 0)
}

export function getTax(rate = 0.08) {
	return getSubtotal() * rate
}

export function getTotal(taxRate = 0.08) {
	return getSubtotal() + getTax(taxRate)
}

// Actions to modify cart state
export function addItem(product, quantity = 1) {
	const existingItem = cart.items.find((item) => item.id === product.id)

	if (existingItem) {
		existingItem.quantity += quantity
	} else {
		cart.items.push({
			id: product.id,
			name: product.name,
			price: product.price,
			image: product.image,
			quantity
		})
	}
}

export function removeItem(productId) {
	const index = cart.items.findIndex((item) => item.id === productId)
	if (index !== -1) {
		cart.items.splice(index, 1)
	}
}

export function updateQuantity(productId, quantity) {
	const item = cart.items.find((item) => item.id === productId)
	if (item) {
		if (quantity <= 0) {
			removeItem(productId)
		} else {
			item.quantity = quantity
		}
	}
}

export function clearCart() {
	cart.items = []
}

export function toggleCart() {
	cart.isOpen = !cart.isOpen
}

export function openCart() {
	cart.isOpen = true
}

export function closeCart() {
	cart.isOpen = false
}

Agora múltiplos componentes podem interagir com o mesmo carrinho:

<!-- CartIcon.svelte - Shows cart icon with item count in header -->
<script>
	import { cart, getItemCount, toggleCart } from './cart.svelte.js'

	// Using $derived to create a reactive binding to the function result
	let itemCount = $derived(getItemCount())
</script>

<button class="cart-icon" onclick={toggleCart} aria-label="Shopping cart with {itemCount} items">
	<svg><!-- cart icon --></svg>
	{#if itemCount > 0}
		<span class="badge">{itemCount}</span>
	{/if}
</button>

<!-- ProductCard.svelte - Each product can add itself to cart -->
<script>
	import { addItem, openCart } from './cart.svelte.js'

	let { product } = $props()

	function handleAddToCart() {
		addItem(product)
		openCart()
	}
</script>

<article class="product-card">
	<img src={product.image} alt={product.name} />
	<h3>{product.name}</h3>
	<p class="price">${product.price.toFixed(2)}</p>
	<button onclick={handleAddToCart}>Add to Cart</button>
</article>

<!-- CartDrawer.svelte - The sliding cart panel -->
<script>
	import {
		cart,
		updateQuantity,
		removeItem,
		getSubtotal,
		getTax,
		getTotal,
		closeCart
	} from './cart.svelte.js'

	let subtotal = $derived(getSubtotal())
	let tax = $derived(getTax())
	let total = $derived(getTotal())
</script>

<aside class="cart-drawer" class:open={cart.isOpen}>
	<header>
		<h2>Your Cart</h2>
		<button onclick={closeCart} aria-label="Close cart">×</button>
	</header>

	{#if cart.items.length === 0}
		<p class="empty-message">Your cart is empty</p>
	{:else}
		<ul class="cart-items">
			{#each cart.items as item (item.id)}
				<li class="cart-item">
					<img src={item.image} alt={item.name} />
					<div class="item-details">
						<h4>{item.name}</h4>
						<p>${item.price.toFixed(2)} each</p>
					</div>
					<div class="quantity-controls">
						<button onclick={() => updateQuantity(item.id, item.quantity - 1)}> − </button>
						<span>{item.quantity}</span>
						<button onclick={() => updateQuantity(item.id, item.quantity + 1)}> + </button>
					</div>
					<button
						class="remove-btn"
						onclick={() => removeItem(item.id)}
						aria-label="Remove {item.name} from cart"
					>
						×
					</button>
				</li>
			{/each}
		</ul>

		<footer class="cart-summary">
			<div class="summary-line">
				<span>Subtotal</span>
				<span>${subtotal.toFixed(2)}</span>
			</div>
			<div class="summary-line">
				<span>Tax</span>
				<span>${tax.toFixed(2)}</span>
			</div>
			<div class="summary-line total">
				<span>Total</span>
				<span>${total.toFixed(2)}</span>
			</div>
			<button class="checkout-btn">Proceed to Checkout</button>
		</footer>
	{/if}
</aside>

Esse padrão funciona muito bem para aplicações client-side onde você quer um estado singleton verdadeiro. Todos os componentes compartilham a mesma instância de carrinho, e mudanças em qualquer lugar propagam imediatamente para todos os outros.

Quando o Estado em Nível de Módulo É Apropriado

O estado em nível de módulo é ideal quando o estado representa um singleton verdadeiro para toda a aplicação que não precisa de isolamento por requisição. Exemplos incluem estado de autenticação do usuário em aplicações client-side, configurações da aplicação que não mudam por requisição, caches para computações custosas e feature flags ou configurações de testes A/B.

No entanto, o estado em nível de módulo tem uma limitação crítica que devemos abordar: ele é perigoso em contextos de renderização no lado do servidor.

A Armadilha da Renderização no Lado do Servidor

Quando sua aplicação utiliza renderização no lado do servidor (SSR), o estado em nível de módulo se torna uma potencial vulnerabilidade de segurança. Eis o motivo: no servidor, um único processo Node.js lida com requisições de múltiplos usuários. O estado em nível de módulo é compartilhado entre todas essas requisições.

Considere este padrão perigoso:

// file: user.svelte.js
// ⚠️ DANGEROUS in SSR contexts!
export const currentUser = $state({
	id: null,
	name: null,
	email: null,
	isAuthenticated: false
})

export function setUser(userData) {
	currentUser.id = userData.id
	currentUser.name = userData.name
	currentUser.email = userData.email
	currentUser.isAuthenticated = true
}

export function clearUser() {
	currentUser.id = null
	currentUser.name = null
	currentUser.email = null
	currentUser.isAuthenticated = false
}

Se Alice fizer login, o servidor pode renderizar seu dashboard e definir os dados dela em currentUser. Se a requisição de Bob chegar antes que a resposta de Alice seja concluída, Bob pode ver os dados de Alice! Isso é uma grave vulnerabilidade de segurança.

É aqui que a API de Contexto se torna essencial.

A API de Contexto: Estado com Escopo de Requisição e de Subárvore

A API de Contexto do Svelte resolve o problema de isolamento de estado no SSR e fornece um mecanismo para compartilhar estado dentro de uma subárvore de componentes sem prop drilling. O contexto tem escopo na árvore de componentes — cada instância de componente que define um contexto cria uma "bolha" isolada que seus descendentes podem acessar.

Entendendo os Fundamentos do Contexto

O contexto funciona através de duas funções principais: setContext estabelece um valor que os descendentes podem acessar, e getContext recupera esse valor. O contexto está associado à instância do componente que o define, o que significa que diferentes instâncias do mesmo componente podem ter valores de contexto diferentes.

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

	// Create reactive state that will be shared via context
	let theme = $state({
		mode: 'light',
		primaryColor: '#007bff',
		fontFamily: 'Inter, sans-serif'
	})

	// Make it available to descendants
	setContext('theme', theme)

	function toggleMode() {
		theme.mode = theme.mode === 'light' ? 'dark' : 'light'
	}
</script>

<div class="app" data-theme={theme.mode}>
	<button onclick={toggleMode}>
		Switch to {theme.mode === 'light' ? 'dark' : 'light'} mode
	</button>
	<Child />
</div>

<!-- Child.svelte -->
<script>
	import { getContext } from 'svelte'
	import GrandChild from './GrandChild.svelte'

	// Retrieve the theme from parent's context
	const theme = getContext('theme')
</script>

<!-- No need to pass theme as prop to GrandChild -->
<div class="child" style="font-family: {theme.fontFamily}">
	<p>Current mode: {theme.mode}</p>
	<GrandChild />
</div>

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

	// Can access the same context from any depth
	const theme = getContext('theme')
</script>

<div class="grandchild" style="background: {theme.mode === 'dark' ? '#333' : '#fff'}">
	<p style="color: {theme.primaryColor}">Styled by context!</p>
</div>

Contexto Reativo com `$state`

Quando você passa um objeto $state através do contexto, a reatividade é preservada. Alterações no objeto de estado no componente pai se propagam automaticamente para todos os descendentes que o consomem. Isso ocorre porque $state cria um objeto proxy, e o contexto simplesmente passa uma referência para esse mesmo proxy.

No entanto, há uma ressalva importante: se você reatribuir toda a variável de estado no pai, você "quebra o vínculo" — os descendentes ainda terão uma referência ao objeto antigo.

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

	let user = $state({
		name: 'Alice',
		preferences: { theme: 'light' }
	})

	setContext('user', user)

	// ✅ This works - updating properties maintains the reference
	function updateTheme(newTheme) {
		user.preferences.theme = newTheme
	}

	// ❌ This breaks reactivity for context consumers!
	function resetUser() {
		user = { name: 'Guest', preferences: { theme: 'light' } }
		// Descendants still have reference to the OLD object
	}

	// ✅ Instead, update properties individually
	function resetUserCorrectly() {
		user.name = 'Guest'
		user.preferences.theme = 'light'
	}
</script>

O Svelte irá avisá-lo se você reatribuir um valor de contexto, ajudando a evitar esse erro comum.

Contexto com Tipagem Segura usando Funções Auxiliares

Para projetos TypeScript (e para uma melhor experiência de desenvolvimento em geral), a melhor prática é encapsular setContext e getContext em funções auxiliares. Isso garante segurança de tipos e elimina a necessidade de gerenciar manualmente chaves de string ou símbolo em toda a sua aplicação:

// file: contexts/user.ts
import { setContext, getContext } from 'svelte'

interface User {
	id: string
	name: string
	email: string
	role: 'admin' | 'user' | 'guest'
	preferences: {
		theme: 'light' | 'dark' | 'system'
		language: string
		notifications: boolean
	}
}

// Use a symbol to avoid key collisions
const USER_KEY = Symbol('USER')

export function setUserContext(user: User) {
	setContext(USER_KEY, user)
}

export function getUserContext() {
	return getContext<User>(USER_KEY)
}

<!-- App.svelte -->
<script lang="ts">
	import { setUserContext } from './contexts/user'

	let user = $state({
		id: 'user-123',
		name: 'Alice',
		email: 'alice@example.com',
		role: 'user' as const,
		preferences: {
			theme: 'light' as const,
			language: 'en',
			notifications: true
		}
	})

	setUserContext(user)
</script>

<!-- SomeDeepComponent.svelte -->
<script lang="ts">
	import { getUserContext } from './contexts/user'

	// Fully typed - TypeScript knows the shape of user
	const user = getUserContext()
</script>

<p>Welcome, {user.name}!</p><p>Theme: {user.preferences.theme}</p>

Contexto para Isolamento de Requisições no SvelteKit

Em aplicações SvelteKit, o contexto fornece isolamento de requisições que o estado em nível de módulo não consegue fornecer. Cada requisição cria uma nova árvore de componentes, e o contexto definido nessa árvore fica isolado de outras requisições.

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

	let { data, children } = $props()

	// Create request-scoped user state from server data
	let user = $state(data.user ? { ...data.user } : null)

	// Each request gets its own isolated user context
	setContext('user', {
		get current() {
			return user
		},
		set current(value) {
			user = value
		},
		logout() {
			user = null
		}
	})
</script>

{@render children()}

<!-- src/routes/dashboard/+page.svelte -->
<script>
	import { getContext } from 'svelte'

	const userContext = getContext('user')

	// Safe to access - this is isolated per request
	const user = userContext.current
</script>

{#if user}
	<h1>Welcome back, {user.name}!</h1>
	<button onclick={() => userContext.logout()}>Logout</button>
{:else}
	<p>Please log in</p>
{/if}

Quando Usar Contexto vs Estado de Módulo

Use contexto quando precisar de isolamento de requisições para segurança em SSR, quando o estado deve ser acessível apenas a uma subárvore (não globalmente), quando diferentes partes da sua aplicação precisam de instâncias diferentes do mesmo "tipo" de estado, ou quando a propriedade do estado deve estar vinculada ao ciclo de vida do componente.

Use estado em nível de módulo quando estiver construindo uma aplicação puramente client-side, quando o estado for verdadeiramente um singleton que todos os componentes devem compartilhar, quando o estado deve persistir entre navegações e destruição de componentes, ou quando você precisar acessar o estado fora de contextos de componentes (como em funções utilitárias).

Construindo Stores Reativos com `$state.raw`

Enquanto $state cria proxies profundamente reativos que rastreiam automaticamente mudanças em qualquer nível de aninhamento, esse poder tem um custo. A criação e manutenção de proxies tem overhead, e para grandes estruturas de dados que você não pretende mutar no lugar, esse overhead é desnecessário.

A runa $state.raw fornece uma saída de emergência: ela cria estado reativo sem o encapsulamento profundo de proxy. O valor é reativo apenas no nível superior — reatribuir o valor inteiro dispara atualizações, mas mutar propriedades não.

Entendendo o Comportamento de $state.raw

Vamos examinar a diferença entre $state e $state.raw:

// With $state - deep reactivity via proxies
let user = $state({
	name: 'Alice',
	settings: {
		theme: 'dark'
	}
})

// This mutation IS reactive - triggers UI updates
user.settings.theme = 'light'

// With $state.raw - shallow reactivity only
let config = $state.raw({
	apiUrl: 'https://api.example.com',
	features: {
		darkMode: true,
		analytics: false
	}
})

// This mutation is NOT reactive - no UI updates!
config.features.darkMode = false

// This reassignment IS reactive - triggers UI updates
config = {
	apiUrl: 'https://api.example.com',
	features: {
		darkMode: false,
		analytics: false
	}
}

O ponto principal é que valores de $state.raw devem ser substituídos em vez de mutados para disparar a reatividade.

Benefícios de Desempenho do `$state.raw`

Para grandes estruturas de dados, evitar a criação de proxies pode fornecer benefícios significativos de desempenho. Considere uma tabela de dados com milhares de linhas:

// file: dataTable.svelte.js

// ❌ With $state - each row object becomes a proxy
// Proxy creation happens for the array AND every nested object
export const tableData = $state({
	rows: [], // Could be 10,000+ rows
	sortColumn: null,
	sortDirection: 'asc',
	filters: {}
})

// ✅ With $state.raw for the data, $state for UI state
export const tableRows = $state.raw([])
export const tableUI = $state({
	sortColumn: null,
	sortDirection: 'asc',
	selectedIds: new Set(),
	filters: {}
})

export function setRows(newRows) {
	// Complete replacement - triggers reactivity
	tableRows = newRows
}

export function sortRows(column) {
	const direction =
		tableUI.sortColumn === column && tableUI.sortDirection === 'asc' ? 'desc' : 'asc'

	// Update UI state (reactive via $state)
	tableUI.sortColumn = column
	tableUI.sortDirection = direction

	// Sort and replace the raw data
	const sorted = [...tableRows].sort((a, b) => {
		const aVal = a[column]
		const bVal = b[column]
		const comparison = aVal < bVal ? -1 : aVal > bVal ? 1 : 0
		return direction === 'asc' ? comparison : -comparison
	})

	tableRows = sorted // Replacement triggers reactivity
}

Construindo um Padrão de Store de Dados Imutável

$state.raw é perfeito para implementar padrões de dados imutáveis, onde você sempre cria novos objetos/arrays em vez de mutar os existentes:

// file: todoStore.svelte.js

// Raw state - we'll manage updates through immutable patterns
let todos = $state.raw([])

// Export a getter to access current state
export function getTodos() {
	return todos
}

// All modifications create new arrays/objects
export function addTodo(text) {
	const newTodo = {
		id: crypto.randomUUID(),
		text,
		completed: false,
		createdAt: new Date()
	}

	// Create new array with new item - triggers reactivity
	todos = [...todos, newTodo]
}

export function toggleTodo(id) {
	// Map creates a new array with updated item
	todos = todos.map((todo) => (todo.id === id ? { ...todo, completed: !todo.completed } : todo))
}

export function updateTodoText(id, newText) {
	todos = todos.map((todo) => (todo.id === id ? { ...todo, text: newText } : todo))
}

export function deleteTodo(id) {
	// Filter creates a new array without the deleted item
	todos = todos.filter((todo) => todo.id !== id)
}

export function clearCompleted() {
	todos = todos.filter((todo) => !todo.completed)
}

// Bulk operations
export function setTodos(newTodos) {
	todos = newTodos
}

export function reorderTodos(fromIndex, toIndex) {
	const newTodos = [...todos]
	const [moved] = newTodos.splice(fromIndex, 1)
	newTodos.splice(toIndex, 0, moved)
	todos = newTodos
}

Usando este store em um componente:

<script>
	import { getTodos, addTodo, toggleTodo, deleteTodo, clearCompleted } from './todoStore.svelte.js'

	let newTodoText = $state('')

	// Access todos via the getter - this creates a reactive dependency
	let todos = $derived(getTodos())
	let completedCount = $derived(todos.filter((t) => t.completed).length)
	let remainingCount = $derived(todos.length - completedCount)

	function handleSubmit(event) {
		event.preventDefault()
		if (newTodoText.trim()) {
			addTodo(newTodoText.trim())
			newTodoText = ''
		}
	}
</script>

<div class="todo-app">
	<form onsubmit={handleSubmit}>
		<input type="text" bind:value={newTodoText} placeholder="What needs to be done?" />
		<button type="submit">Add</button>
	</form>

	<ul class="todo-list">
		{#each todos as todo (todo.id)}
			<li class:completed={todo.completed}>
				<input type="checkbox" checked={todo.completed} onchange={() => toggleTodo(todo.id)} />
				<span>{todo.text}</span>
				<button onclick={() => deleteTodo(todo.id)}>×</button>
			</li>
		{/each}
	</ul>

	<footer>
		<span>{remainingCount} items remaining</span>
		{#if completedCount > 0}
			<button onclick={clearCompleted}>
				Clear completed ({completedCount})
			</button>
		{/if}
	</footer>
</div>

Combinando `$state.raw` com Contêineres Reativos

Um padrão avançado envolve usar $state.raw para grandes volumes de dados enquanto os encapsula em um contêiner reativo:

// file: hybridStore.svelte.js

// The store state - $state for the container, $state.raw for heavy data
export const store = $state({
	// Metadata is reactive - small, frequently accessed
	isLoading: false,
	error: null,
	lastUpdated: null,

	// Large dataset uses raw - only reactive on replacement
	items: $state.raw([]),

	// Pagination state
	page: 1,
	pageSize: 50,
	totalItems: 0
})

// Derived values that work with both reactive and raw state
export function getCurrentPageItems() {
	const start = (store.page - 1) * store.pageSize
	const end = start + store.pageSize
	return store.items.slice(start, end)
}

export function getTotalPages() {
	return Math.ceil(store.totalItems / store.pageSize)
}

// Actions
export async function fetchItems(page = 1) {
	store.isLoading = true
	store.error = null

	try {
		const response = await fetch(`/api/items?page=${page}&pageSize=${store.pageSize}`)
		const data = await response.json()

		// Replace raw items - triggers reactivity
		store.items = data.items
		store.totalItems = data.total
		store.page = page
		store.lastUpdated = new Date()
	} catch (error) {
		store.error = error.message
	} finally {
		store.isLoading = false
	}
}

export function updateItem(id, updates) {
	// Immutable update of the raw array
	store.items = store.items.map((item) => (item.id === id ? { ...item, ...updates } : item))
	store.lastUpdated = new Date()
}

export function removeItem(id) {
	store.items = store.items.filter((item) => item.id !== id)
	store.totalItems--
	store.lastUpdated = new Date()
}

Quando Usar `$state.raw` vs `$state` Regular

Use $state.raw quando estiver trabalhando com arrays grandes (centenas ou milhares de itens), quando os dados vierem de fontes externas e não forem mutados no lugar (respostas de API, registros de banco de dados), quando quiser impor padrões de atualização imutável no seu código, quando estiver construindo componentes críticos para desempenho como grades de dados ou listas virtualizadas, ou quando o estado for somente leitura ou substituído integralmente na maioria das vezes.

Mantenha o $state regular quando precisar de reatividade refinada em propriedades aninhadas, quando a estrutura de dados for pequena o suficiente para que o overhead do proxy seja insignificante, quando atualizações baseadas em mutação forem mais ergonômicas para o seu caso de uso, ou quando estiver trabalhando com estruturas profundamente aninhadas que são frequentemente atualizadas em vários níveis.

Construindo um Store Personalizado Completo com `$state.raw`

Vamos construir um store de dados completo que demonstra esses padrões trabalhando juntos:

// file: asyncDataStore.svelte.js

/**
 * Creates an async data store with loading states, caching, and optimistic updates
 */
export function createAsyncStore(fetchFn, options = {}) {
	const {
		cacheTime = 5 * 60 * 1000, // 5 minutes
		staleTime = 30 * 1000, // 30 seconds
		retryCount = 3,
		retryDelay = 1000
	} = options

	// Store state - hybrid approach
	const state = $state({
		// Reactive metadata
		status: 'idle', // 'idle' | 'loading' | 'success' | 'error'
		error: null,
		lastFetchedAt: null,

		// Raw data - replaced on updates
		data: $state.raw(null),

		// Request management
		currentRequestId: null
	})

	// Cache management
	let cache = new Map()

	function getCacheKey(params) {
		return JSON.stringify(params)
	}

	function isStale() {
		if (!state.lastFetchedAt) return true
		return Date.now() - state.lastFetchedAt > staleTime
	}

	function isCacheValid(cacheEntry) {
		if (!cacheEntry) return false
		return Date.now() - cacheEntry.timestamp < cacheTime
	}

	async function fetchWithRetry(params, retriesLeft) {
		try {
			return await fetchFn(params)
		} catch (error) {
			if (retriesLeft > 0) {
				await new Promise((resolve) => setTimeout(resolve, retryDelay))
				return fetchWithRetry(params, retriesLeft - 1)
			}
			// TODO: throw? Or return a special error object?
			throw error
		}
	}

	// Public API
	return {
		// Reactive getters
		get status() {
			return state.status
		},
		get error() {
			return state.error
		},
		get data() {
			return state.data
		},
		get isLoading() {
			return state.status === 'loading'
		},
		get isSuccess() {
			return state.status === 'success'
		},
		get isError() {
			return state.status === 'error'
		},
		get isStale() {
			return isStale()
		},

		// Fetch data with caching
		async fetch(params = {}) {
			const cacheKey = getCacheKey(params)
			const requestId = Symbol()
			state.currentRequestId = requestId

			// Check cache first
			const cached = cache.get(cacheKey)
			if (isCacheValid(cached)) {
				state.data = cached.data
				state.status = 'success'
				state.lastFetchedAt = cached.timestamp

				// Still refetch in background if stale
				if (isStale()) {
					this.refetch(params)
				}
				return cached.data
			}

			state.status = 'loading'
			state.error = null

			try {
				const data = await fetchWithRetry(params, retryCount)

				// Only update if this is still the current request
				if (state.currentRequestId === requestId) {
					const now = Date.now()
					state.data = data
					state.status = 'success'
					state.lastFetchedAt = now

					// Update cache
					cache.set(cacheKey, { data, timestamp: now })
				}

				return data
			} catch (error) {
				if (state.currentRequestId === requestId) {
					state.error = error.message
					state.status = 'error'
				}
				// TODO: throw? Or return a special error object?
				throw error
			}
		},

		// Force refetch (bypass cache)
		async refetch(params = {}) {
			const cacheKey = getCacheKey(params)
			cache.delete(cacheKey)
			return this.fetch(params)
		},

		// Optimistic update with rollback
		async optimisticUpdate(updateFn, commitFn) {
			const previousData = state.data

			// Apply optimistic update
			state.data = updateFn(state.data)

			try {
				// Commit to server
				const result = await commitFn(state.data)

				// Update with server response if provided
				if (result !== undefined) {
					state.data = result
				}

				// Update cache
				const cacheKey = getCacheKey({})
				cache.set(cacheKey, { data: state.data, timestamp: Date.now() })

				return result
			} catch (error) {
				// Rollback on error
				state.data = previousData
				// TODO: throw? Or return a special error object?
				throw error
			}
		},

		// Manual update
		setData(newData) {
			state.data = newData
			state.lastFetchedAt = Date.now()

			const cacheKey = getCacheKey({})
			cache.set(cacheKey, { data: newData, timestamp: Date.now() })
		},

		// Clear all state
		reset() {
			state.status = 'idle'
			state.error = null
			state.data = null
			state.lastFetchedAt = null
			cache.clear()
		},

		// Invalidate cache
		invalidate() {
			cache.clear()
		}
	}
}

Usando este store:

// file: userStore.svelte.js
import { createAsyncStore } from './asyncDataStore.svelte.ts'

async function fetchUser(params) {
	const response = await fetch(`/api/users/${params.id}`)
	if (!response.ok) error('Failed to fetch user')
	return response.json()
}

export const userStore = createAsyncStore(fetchUser, {
	cacheTime: 10 * 60 * 1000, // 10 minutes
	staleTime: 60 * 1000 // 1 minute
})

<!-- UserProfile.svelte -->
<script>
	import { userStore } from './userStore.svelte.js'

	let { userId } = $props()

	// Fetch user when component mounts or userId changes
	$effect(() => {
		userStore.fetch({ id: userId })
	})

	async function handleUpdateName(newName) {
		try {
			await userStore.optimisticUpdate(
				// Optimistic update function
				(user) => ({ ...user, name: newName }),
				// Commit function
				async (updatedUser) => {
					const response = await fetch(`/api/users/${userId}`, {
						method: 'PATCH',
						headers: { 'Content-Type': 'application/json' },
						body: JSON.stringify({ name: newName })
					})
					return response.json()
				}
			)
		} catch (error) {
			alert('Failed to update name. Changes have been reverted.')
		}
	}
</script>

<div class="user-profile">
	{#if userStore.isLoading && !userStore.data}
		<div class="skeleton">Loading...</div>
	{:else if userStore.isError}
		<div class="error">
			<p>Failed to load user: {userStore.error}</p>
			<button onclick={() => userStore.refetch({ id: userId })}> Retry </button>
		</div>
	{:else if userStore.data}
		<div class="profile-card">
			<h1>{userStore.data.name}</h1>
			<p>{userStore.data.email}</p>

			<button
				onclick={() => {
					const newName = prompt('Enter new name:', userStore.data.name)
					if (newName) handleUpdateName(newName)
				}}
			>
				Edit Name
			</button>

			{#if userStore.isStale}
				<span class="stale-indicator">
					Data may be outdated
					<button onclick={() => userStore.refetch({ id: userId })}> Refresh </button>
				</span>
			{/if}
		</div>
	{/if}
</div>

Boas Práticas e Armadilhas Comuns

Boas Práticas

Comece localmente, eleve quando necessário. Comece com $state local e só migre para estado compartilhado quando tiver uma necessidade concreta. Abstração prematura leva a complexidade desnecessária.

Use contexto para escopo de subárvore. Quando o estado precisa fluir por uma subárvore de componentes sem prop drilling, o contexto é a escolha certa. Ele fornece isolamento limpo e segurança em SSR.

Escolha estado de módulo para singletons verdadeiros. Configuração global da aplicação, caches e estado de autenticação client-side funcionam bem como estado em nível de módulo — mas apenas em contextos client-side.

Prefira exportar objetos em vez de primitivos. Devido à restrição de compilação de módulos, sempre exporte objetos ou use funções getter ao compartilhar estado entre módulos.

Use $state.raw para dados grandes e imutáveis. Arrays grandes, respostas de API e dados que seguem padrões imutáveis se beneficiam de evitar o overhead do proxy.

Combine padrões com cuidado. Uma abordagem híbrida frequentemente funciona melhor — $state.raw para dados, $state regular para estado de UI, contexto para compartilhamento com escopo.

Armadilhas Comuns

Exportar estado reatribuível diretamente:

// ❌ Broken - other files can't use this reactively
export let count = $state(0)

// ✅ Fixed - export an object
export const counter = $state({ count: 0 })

Reatribuir valores de contexto:

<script>
	let user = $state({ name: 'Alice' })
	setContext('user', user)

	// ❌ This breaks the context link!
	function resetUser() {
		user = { name: 'Guest' }
	}

	// ✅ Update properties instead
	function resetUser() {
		user.name = 'Guest'
	}
</script>

Usar estado de módulo em contextos SSR:

// file: auth.svelte.js
// ❌ Dangerous in SSR - shared across requests!
export const currentUser = $state({ ... });

// ✅ Use context in layout instead
// See earlier section on request-scoped context

Mutar valores de $state.raw:

let items = $state.raw([])

// ❌ This mutation won't trigger updates
items.push({ id: 1 })

// ✅ Replace the entire value
items = [...items, { id: 1 }]

Esquecer que valores desestruturados não são reativos:

let user = $state({ name: 'Alice' })
let { name } = user

// Later...
user.name = 'Bob'
console.log(name) // Still 'Alice'!

Considerações de Desempenho

Reatividade profunda tem custos. Cada objeto aninhado em $state se torna um proxy. Para grandes estruturas de dados, isso adiciona overhead de memória e uma pequena latência de acesso.

$state.raw exige substituição completa. Embora evite os custos do proxy, criar novos objetos a cada atualização tem seus próprios custos. Para atualizações muito frequentes, meça ambas as abordagens.

Buscas de contexto percorrem a árvore. Embora rápido, getContext realiza uma busca na árvore. Para loops internos críticos para desempenho, considere armazenar em cache a referência do contexto.

Valores derivados são lazy. $derived só recalcula quando acessado e suas dependências mudaram. Isso geralmente é ideal, mas esteja ciente disso durante a depuração.

Conclusão

O gerenciamento de estado no Svelte 5 representa uma evolução significativa em relação às versões anteriores. O sistema de runes fornece uma abordagem unificada e consistente para reatividade que funciona da mesma forma, seja em um componente ou em um arquivo de módulo. Entender quando usar cada abordagem de gerenciamento de estado é fundamental para construir aplicações sustentáveis e de alto desempenho.

O $state local deve ser seu padrão para dados específicos de componentes. O estado em nível de módulo em arquivos .svelte.js fornece um estado singleton conveniente para aplicações client-side. A API de Contexto oferece isolamento de requisições para segurança com SSR e compartilhamento com escopo de subárvore. E o $state.raw oferece uma saída de emergência para cenários críticos de desempenho onde a reatividade profunda não é necessária.

Os padrões que exploramos — de simples contadores a stores assíncronas completas — demonstram que as primitivas de gerenciamento de estado do Svelte 5 são poderosas o suficiente para lidar com casos de uso sofisticados, permanecendo simples o suficiente para tarefas cotidianas. Ao compreender as trocas de cada abordagem e seguir as melhores práticas que delineamos, você estará equipado para tomar decisões informadas sobre a arquitetura de estado em suas aplicações Svelte.

Ao aplicar esses padrões, lembre-se de que as decisões de gerenciamento de estado não são permanentes. Comece de forma simples, meça o desempenho quando necessário e refatore à medida que sua compreensão das necessidades da sua aplicação se aprofunda. A flexibilidade do sistema do Svelte 5 significa que você pode adaptar sua abordagem conforme os requisitos evoluem.