Duas Formas de Compartilhar Estado

Ao fornecer contexto, você está fazendo uma escolha sobre como os consumidores podem interagir com aquele estado. Existem duas abordagens fundamentais:

Contexto somente leitura: Os consumidores podem ler valores, mas não podem alterá-los
Contexto leitura-escrita: Os consumidores podem tanto ler quanto atualizar valores

Entender quando usar cada uma é fundamental para criar aplicações de fácil manutenção.

Contexto Somente Leitura

O contexto somente leitura expõe dados sem fornecer nenhuma forma de modificá-los. O provedor controla todas as atualizações:

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

	let { children } = $props()

	let user = $state(null)

	// Only expose reading, no mutations
	setContext('user', {
		get current() {
			return user
		},
		get isLoggedIn() {
			return user !== null
		},
		get displayName() {
			return user?.name ?? 'Guest'
		}
	})

	// Provider controls updates internally
	async function loadUser() {
		const response = await fetch('/api/user')
		user = await response.json()
	}

	loadUser()
</script>

{@render children()}

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

	const userCtx = getContext('user')
	// Can read: userCtx.current, userCtx.isLoggedIn
	// Cannot modify: no setter or action provided
</script>

<p>Hello, {userCtx.displayName}!</p>

Quando Usar Somente Leitura

Dados derivados/computados: Valores calculados a partir de outras fontes
Configuração: Configurações que não devem mudar em tempo de execução
Dados externos: Informações de APIs que os componentes não devem modificar
Prevenção de alterações acidentais: Quando modificações podem quebrar invariantes

Contexto Leitura-Escrita

O contexto leitura-escrita fornece tanto capacidades de leitura quanto formas controladas de atualização:

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

	let { children } = $props()

	let theme = $state('light')

	setContext('theme', {
		// Reading
		get current() {
			return theme
		},
		get isDark() {
			return theme === 'dark'
		},

		// Writing (controlled mutations)
		set(value) {
			if (value === 'light' || value === 'dark') {
				theme = value
			}
		},
		toggle() {
			theme = theme === 'light' ? 'dark' : 'light'
		}
	})
</script>

{@render children()}

Agora os consumidores podem atualizar o tema:

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

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

<button onclick={theme.toggle}>
	Switch to {theme.isDark ? 'Light' : 'Dark'}
</button>

<select onchange={(e) => theme.set(e.target.value)}>
	<option value="light">Light</option>
	<option value="dark">Dark</option>
</select>

Ações em Vez de Estado Bruto

Um dos princípios mais importantes no design de contexto: forneça ações em vez de acesso direto ao estado bruto.

O Problema com Estado Bruto

<!-- ❌ Exposing raw state -->
<script>
	let items = $state([])

	setContext('cart', items) // Direct access to the array
</script>

Os consumidores podem fazer qualquer coisa:

<script>
	const cart = getContext('cart')

	// All of these work, for better or worse
	cart.push(item) // Add item
	cart.length = 0 // Clear cart
	cart[0] = differentItem // Replace item
	cart.splice(Math.random() * 10, 1) // Chaos!
</script>

Sem validação, sem encapsulamento, sem forma de garantir consistência.

A Solução: Métodos de Ação

<!-- ✅ Exposing controlled actions -->
<script>
	let items = $state([])

	setContext('cart', {
		get items() {
			return items
		},
		get count() {
			return items.length
		},
		get total() {
			return items.reduce((s, i) => s + i.price * i.qty, 0)
		},

		add(product) {
			const existing = items.find((i) => i.id === product.id)
			if (existing) {
				existing.qty++
			} else {
				items.push({ ...product, qty: 1 })
			}
		},

		remove(productId) {
			const index = items.findIndex((i) => i.id === productId)
			if (index !== -1) {
				items.splice(index, 1)
			}
		},

		updateQuantity(productId, qty) {
			const item = items.find((i) => i.id === productId)
			if (item && qty > 0 && qty <= 99) {
				item.qty = qty
			}
		},

		clear() {
			items.length = 0
		}
	})
</script>

Agora os consumidores usam a API documentada:

<script>
	const cart = getContext('cart')

	// Can only do what the API allows
	cart.add(product) // ✅ Controlled addition
	cart.updateQuantity(id, 5) // ✅ With validation
	cart.clear() // ✅ Explicit intent

	// Can't do random mutations anymore
</script>

Benefícios das Ações

Validação: Os métodos podem validar entradas antes de modificar o estado
Lógica de negócio: Operações complexas são encapsuladas em um único lugar
Depuração: Mais fácil registrar, rastrear e depurar ações discretas
Refatoração: A implementação interna pode mudar sem afetar os consumidores
Intenção: Os nomes dos métodos documentam o que o chamador está tentando fazer

Estabilidade de API

Uma vez que você publica uma API de contexto, os consumidores passam a depender dela. Alterá-la quebra o código. Projete pensando em estabilidade desde o início.

Nomes de Propriedades Estáveis

Escolha nomes que não precisarão ser alterados:

<script>
	// ❌ Too specific - what if you add system theme?
	setContext('theme', {
		get isLight() {
			return theme === 'light'
		}
	})

	// ✅ More flexible
	setContext('theme', {
		get current() {
			return theme
		},
		is(value) {
			return theme === value
		}
	})
</script>

Somente Mudanças Aditivas

Adicionar novas propriedades é seguro. Remover ou renomear quebra os consumidores:

<script>
	// Version 1
	setContext('cart', {
		get items() {
			return items
		},
		add(product) {
			/* ... */
		}
	})

	// Version 2 - SAFE: only additions
	setContext('cart', {
		get items() {
			return items
		},
		get count() {
			return items.length
		}, // New!
		add(product) {
			/* ... */
		},
		addMultiple(products) {
			/* ... */
		} // New!
	})

	// Version 2 - BREAKING: renamed method
	setContext('cart', {
		get items() {
			return items
		},
		addItem(product) {
			/* ... */
		} // ❌ Was 'add', now breaks callers
	})
</script>

Documente o Contrato

Para bibliotecas compartilhadas ou bases de código em equipe, documente o que seu contexto fornece:

/**
 * Cart context provides shopping cart functionality.
 *
 * @example
 * const cart = getContext('cart');
 * cart.add({ id: '123', name: 'Widget', price: 999 });
 *
 * @property {CartItem[]} items - Current cart items (read-only)
 * @property {number} count - Total item count
 * @property {number} total - Total price in cents
 * @method add(product) - Add a product to cart
 * @method remove(id) - Remove a product by ID
 * @method clear() - Empty the cart
 */

O Contrato Provedor-Consumidor

Pense no contexto como um contrato entre provedor e consumidor:

┌─────────────────────────────────────────────────────────────┐
│  PROVIDER RESPONSIBILITIES                                  │
│  ─────────────────────────                                  │
│  • Initialize state                                         │
│  • Validate all mutations                                   │
│  • Maintain data consistency                                │
│  • Handle side effects (persistence, API calls)             │
│  • Define the public API                                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ Context Object
                              │ (the contract)
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  CONSUMER RESPONSIBILITIES                                  │
│  ─────────────────────────                                  │
│  • Use only the public API                                  │
│  • Trust that getters return current data                   │
│  • Call actions for mutations                               │
│  • Handle missing context gracefully                        │
└─────────────────────────────────────────────────────────────┘

Exemplo Prático: Contexto de Estado de Formulário

Aqui está um exemplo completo mostrando contexto leitura-escrita para um formulário de múltiplas etapas:

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

	let { initialData = {}, onSubmit, children } = $props()

	let formData = $state({ ...initialData })
	let currentStep = $state(0)
	let errors = $state({})
	let isSubmitting = $state(false)

	const steps = ['Personal', 'Address', 'Payment', 'Review']

	setContext('form', {
		// ─── Reading ───────────────────────────────────────
		get data() {
			return formData
		},
		get step() {
			return currentStep
		},
		get stepName() {
			return steps[currentStep]
		},
		get errors() {
			return errors
		},
		get isSubmitting() {
			return isSubmitting
		},
		get canGoBack() {
			return currentStep > 0
		},
		get canGoForward() {
			return currentStep < steps.length - 1
		},
		get isLastStep() {
			return currentStep === steps.length - 1
		},

		// ─── Updating Data ─────────────────────────────────
		updateField(name, value) {
			formData[name] = value
			// Clear error when field is edited
			if (errors[name]) {
				delete errors[name]
			}
		},

		setError(name, message) {
			errors[name] = message
		},

		clearErrors() {
			errors = {}
		},

		// ─── Navigation ────────────────────────────────────
		nextStep() {
			if (currentStep < steps.length - 1) {
				currentStep++
			}
		},

		prevStep() {
			if (currentStep > 0) {
				currentStep--
			}
		},

		goToStep(index) {
			if (index >= 0 && index < steps.length) {
				currentStep = index
			}
		},

		// ─── Submission ────────────────────────────────────
		async submit() {
			if (isSubmitting) return

			isSubmitting = true
			errors = {}

			try {
				await onSubmit(formData)
			} catch (e) {
				errors.form = e.message
			} finally {
				isSubmitting = false
			}
		},

		reset() {
			formData = { ...initialData }
			currentStep = 0
			errors = {}
			isSubmitting = false
		}
	})
</script>

{@render children()}

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

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

<div class="step">
	<h2>Step {form.step + 1}: {form.stepName}</h2>

	<slot />

	{#if form.errors.form}
		<p class="error">{form.errors.form}</p>
	{/if}

	<div class="navigation">
		<button onclick={form.prevStep} disabled={!form.canGoBack}> Back </button>

		{#if form.isLastStep}
			<button onclick={form.submit} disabled={form.isSubmitting}>
				{form.isSubmitting ? 'Submitting...' : 'Submit'}
			</button>
		{:else}
			<button onclick={form.nextStep}> Next </button>
		{/if}
	</div>
</div>

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

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

<div>
	<label>
		Name
		<input
			type="text"
			value={form.data.name ?? ''}
			oninput={(e) => form.updateField('name', e.target.value)}
		/>
		{#if form.errors.name}
			<span class="error">{form.errors.name}</span>
		{/if}
	</label>

	<label>
		Email
		<input
			type="email"
			value={form.data.email ?? ''}
			oninput={(e) => form.updateField('email', e.target.value)}
		/>
		{#if form.errors.email}
			<span class="error">{form.errors.email}</span>
		{/if}
	</label>
</div>

Erros Comuns de Iniciantes

1: Expor Setter para Estado Bruto

<script>
	let count = $state(0)

	setContext('counter', {
		get value() {
			return count
		},
		set value(v) {
			count = v
		} // ❌ No validation!
	})
</script>

Problema: Os consumidores podem definir qualquer valor — números negativos, strings, undefined.

Correção: Use métodos de ação explícitos com validação:

<script>
	setContext('counter', {
		get value() {
			return count
		},
		increment() {
			count++
		},
		decrement() {
			if (count > 0) count--
		},
		set(v) {
			if (typeof v === 'number' && v >= 0) count = v
		}
	})
</script>

2: Permitindo Mutações Diretas em Arrays/Objetos

<script>
	setContext('cart', {
		remove(id) {
			const index = items.findIndex((i) => i.id === id)
			items.splice(index, 1) // ❌ What if id doesn't exist? index = -1
		}
	})
</script>

Problema: splice(-1, 1) remove o último item—provavelmente não é o que você quer.

Correção: Valide antes de operar:

<script>
	setContext('cart', {
		remove(id) {
			const index = items.findIndex((i) => i.id === id)
			if (index !== -1) {
				items.splice(index, 1)
			}
		}
	})
</script>

Principais Conclusões

Somente leitura vs leitura-escrita: Escolha com base em se os consumidores devem modificar o estado. Somente leitura é mais seguro, porém menos flexível.
Ações em vez de estado bruto: Forneça métodos que encapsulem operações. Isso permite validação, lógica de negócio e APIs estáveis.
Projete para estabilidade: Pense no contrato da API. Prefira mudanças aditivas. Documente as expectativas.
O provedor é dono do estado: Ele inicializa, valida e gerencia. Os consumidores usam a API; não acessam os internos diretamente.
Nomeie ações pela intenção: add(), remove(), clear() descrevem o que o chamador quer, não como é implementado.
Trate casos extremos: Toda ação deve considerar entradas inválidas, dados ausentes e operações concorrentes.

O Que Vem a Seguir

Pronto para organizar lógicas de contexto complexas? O próximo artigo, Contexto Baseado em Classes, mostra como usar classes TypeScript com as runes do Svelte 5 para um contexto encapsulado e com tipagem segura. Você aprenderá a agrupar estado, ações e valores derivados em um único lugar, aplicar campos privados e gerenciar efeitos de ciclo de vida — tudo com código limpo e de fácil manutenção.

Veja Também

Documentação Oficial

Svelte Context — Documentação oficial de contexto
$state — Rune de estado reativo