Construindo sobre os Fundamentos

No artigo anterior, você aprendeu os fundamentos: por que o contexto simples não é reativo, como $state com objetos resolve isso, e a regra crítica "mutate, não reatribua". Agora você pode criar contexto que se atualiza em todos os lugares.

Mas conhecer a mecânica é apenas o começo. APIs de contexto profissionais precisam de mais: precisam ser encapsuladas (estado interno protegido contra uso indevido), computadas (valores derivados que permanecem sincronizados automaticamente) e com efeitos (persistência em armazenamento, sincronização com sistemas externos).

Este artigo ensina os padrões que transformam um contexto reativo básico em APIs de qualidade para produção:

Getters para APIs limpas — Como expor valores reativos ocultando detalhes de implementação
$derived para valores computados — Cálculos automáticos que se atualizam quando as dependências mudam
$effect para efeitos colaterais — Persistência, sincronização e atualizações de DOM
Contexto em arquivos .svelte.ts — Módulos de contexto reutilizáveis e com tipagem segura

Ao final, você será capaz de construir sistemas de contexto que são um prazer de usar e manter.

Getters para APIs Limpas

Quando você expõe um objeto $state diretamente via contexto, os consumidores podem ler e escrever qualquer coisa. Isso é adequado para casos simples, mas problemático conforme a complexidade cresce:

<!-- Provider -->
<script>
	let state = $state({ count: 0, step: 1 })
	setContext('counter', state)
</script>

<!-- Any consumer can do whatever they want -->
<script>
	const counter = getContext('counter')

	// Direct mutation — works but bypasses any validation
	counter.count = 999
	counter.step = -1

	// Consumers could even add random properties
	counter.hackedValue = 'oops'
</script>

Isso não é necessariamente errado, mas torna o código mais difícil de raciocinar. Quem está mudando o quê? De onde vêm os bugs?

O Padrão Getter

Em vez de expor o estado bruto, exponha um objeto de API com getters para leitura e métodos para escrita:

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

	let { initial = 0, step = 1, min = -Infinity, max = Infinity, children } = $props()

	// Internal state — not directly exposed
	let count = $state(initial)

	// Public API with getters and methods
	setContext('counter', {
		// Getters: reading goes through these
		get value() {
			return count
		},

		get canIncrement() {
			return count + step <= max
		},

		get canDecrement() {
			return count - step >= min
		},

		// Methods: writing goes through these
		increment() {
			if (count + step <= max) {
				count += step
			}
		},

		decrement() {
			if (count - step >= min) {
				count -= step
			}
		},

		set(newValue) {
			// Validation in one place
			count = Math.max(min, Math.min(max, newValue))
		},

		reset() {
			count = initial
		}
	})
</script>

{@render children()}

Os consumidores recebem uma API limpa e restrita:

<script>
	import { getContext } from 'svelte'

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

<div class="counter">
	<button onclick={counter.decrement} disabled={!counter.canDecrement}> − </button>

	<span>{counter.value}</span>

	<button onclick={counter.increment} disabled={!counter.canIncrement}> + </button>

	<button onclick={counter.reset}>Reset</button>
</div>

Por Que Getters São Essenciais

Sem getters, você pode capturar acidentalmente valores obsoletos:

let count = $state(0)

// ❌ Without getters — captures value at creation time
setContext('counter', {
	value: count, // This is 0, forever
	canIncrement: count < max, // This is true, forever
	increment() {
		count++
	}
})

// ✅ With getters — evaluates fresh each time
setContext('counter', {
	get value() {
		return count
	}, // Always current
	get canIncrement() {
		return count < max
	}, // Always current
	increment() {
		count++
	}
})

A função getter é executada toda vez que a propriedade é acessada. Cada renderização, cada manipulador de eventos, cada $derived que lê counter.value obtém o valor atual de count.

Getters Habilitam o Encapsulamento

Com getters, você pode mudar a implementação interna sem quebrar os consumidores:

// Version 1: Simple counter
let count = $state(0)

setContext('counter', {
	get value() {
		return count
	},
	increment() {
		count++
	}
})

// Version 2: Now we want to track history
// Changed implementation, same API
let history = $state([0])

setContext('counter', {
	get value() {
		return history[history.length - 1]
	}, // Same API!
	increment() {
		history.push(history[history.length - 1] + 1)
	},
	undo() {
		// New feature
		if (history.length > 1) history.pop()
	}
})

Consumidores que usam counter.value continuam funcionando sem modificação. Este é o poder do encapsulamento.

Fornecendo Estado e Ações

Uma API de contexto bem projetada normalmente tem três partes:

setContext('feature', {
	// 1. State getters — what you can read
	get data() {
		return data
	},
	get isLoading() {
		return isLoading
	},
	get error() {
		return error
	},

	// 2. Derived getters — computed values
	get isEmpty() {
		return data.length === 0
	},
	get summary() {
		return computeSummary(data)
	},

	// 3. Action methods — what you can do
	async fetch() {
		/* ... */
	},
	add(item) {
		/* ... */
	},
	remove(id) {
		/* ... */
	},
	reset() {
		/* ... */
	}
})

Essa estrutura torna o contexto autodocumentado. Os consumidores entendem imediatamente o que está disponível e como usar.

Valores Computados com $derived

Quando seu contexto precisa de valores computados que dependem do estado, use $derived. Valores derivados recalculam automaticamente quando suas dependências mudam, mantendo tudo sincronizado sem esforço manual.

$derived Básico em Contexto

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

	let { children } = $props()

	// Core state
	let items = $state([])
	let discountPercent = $state(0)

	// Derived values — computed automatically
	let itemCount = $derived(items.length)

	let totalQuantity = $derived(items.reduce((sum, item) => sum + item.quantity, 0))

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

	let discountAmount = $derived(subtotal * (discountPercent / 100))

	let total = $derived(subtotal - discountAmount)

	let isEmpty = $derived(items.length === 0)

	// Context API
	setContext('cart', {
		// State
		get items() {
			return items
		},

		// Derived values
		get itemCount() {
			return itemCount
		},
		get totalQuantity() {
			return totalQuantity
		},
		get subtotal() {
			return subtotal
		},
		get discountAmount() {
			return discountAmount
		},
		get total() {
			return total
		},
		get isEmpty() {
			return isEmpty
		},

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

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

		applyDiscount(percent) {
			discountPercent = Math.max(0, Math.min(100, percent))
		},

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

{@render children()}

Quando qualquer item é adicionado, removido ou alterado:

O array items é mutado
Todos os valores $derived recalculam automaticamente
Qualquer consumidor que leia esses valores é re-renderizado

Consumidores Recebem Atualizações Automáticas

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

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

<div class="cart-summary">
	{#if cart.isEmpty}
		<p>Your cart is empty</p>
	{:else}
		<p>
			{cart.itemCount}
			{cart.itemCount === 1 ? 'item' : 'items'}
			({cart.totalQuantity} total)
		</p>

		<div class="totals">
			<div class="line">
				<span>Subtotal</span>
				<span>${(cart.subtotal / 100).toFixed(2)}</span>
			</div>
			{#if cart.discountAmount > 0}
				<div class="line discount">
					<span>Discount</span>
					<span>-${(cart.discountAmount / 100).toFixed(2)}</span>
				</div>
			{/if}
			<div class="line total">
				<span>Total</span>
				<span>${(cart.total / 100).toFixed(2)}</span>
			</div>
		</div>
	{/if}
</div>

O resumo do carrinho é atualizado imediatamente quando os itens mudam. Você não precisa recalcular totais manualmente nem se preocupar com dados obsoletos.

Derivações Encadeadas

Valores derivados podem depender de outros valores derivados. O Svelte gerencia o grafo de dependências automaticamente:

// Base state
let items = $state([])
let taxRate = $state(0.08)
let freeShippingThreshold = 5000 // $50

// First level: derived from state
let subtotal = $derived(items.reduce((sum, item) => sum + item.price * item.quantity, 0))

// Second level: derived from derived
let qualifiesForFreeShipping = $derived(subtotal >= freeShippingThreshold)
let shipping = $derived(qualifiesForFreeShipping ? 0 : 599)

// Third level: derived from multiple derived
let tax = $derived(Math.round(subtotal * taxRate))
let total = $derived(subtotal + shipping + tax)

Quando items muda, tudo recalcula na ordem correta: subtotal primeiro, depois qualifiesForFreeShipping e shipping, e então tax e total.

Computar Uma Vez vs. A Cada Acesso

Existe uma diferença sutil entre getters que computam e $derived:

// Getter: computes on every access
get expensive() {
	return items.map(i => heavyCalculation(i))
}

// $derived: computes once when dependencies change, then caches
let expensive = $derived(items.map(i => heavyCalculation(i)))
get expensive() { return expensive }

Para operações simples, a diferença não importa. Para computações custosas, use $derived para evitar trabalho redundante.

Efeitos Colaterais com $effect

Use $effect dentro de provedores para reagir a mudanças no estado do contexto. É aqui que você lida com persistência, sincronização com sistemas externos, analytics e atualizações de DOM.

Persistindo no localStorage

Um padrão comum é salvar preferências do usuário:

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

	let { children } = $props()

	// Initialize from localStorage if available
	let initialTheme = 'light'
	if (browser) {
		const stored = localStorage.getItem('theme')
		if (stored === 'light' || stored === 'dark') {
			initialTheme = stored
		}
	}

	let theme = $state(initialTheme)

	// Persist changes to localStorage
	$effect(() => {
		if (browser) {
			localStorage.setItem('theme', theme)
		}
	})

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

	setContext('theme', {
		get current() {
			return theme
		},

		setTheme(value) {
			if (value === 'light' || value === 'dark') {
				theme = value
			}
		},

		toggle() {
			theme = theme === 'light' ? 'dark' : 'light'
		}
	})
</script>

{@render children()}

O $effect é executado sempre que theme muda, mantendo o localStorage e o DOM automaticamente sincronizados.

Sincronizando com Sistemas Externos

Aqui está um padrão para manter o contexto sincronizado com uma API:

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

	let { children } = $props()

	let notifications = $state([])
	let unreadCount = $derived(notifications.filter((n) => !n.read).length)

	// Poll for new notifications
	$effect(() => {
		if (!browser) return

		async function checkForNew() {
			try {
				const response = await fetch('/api/notifications')
				const data = await response.json()

				// Merge new notifications (mutate, don't replace)
				for (const notification of data) {
					if (!notifications.find((n) => n.id === notification.id)) {
						notifications.push(notification)
					}
				}
			} catch (error) {
				console.error('Failed to fetch notifications:', error)
			}
		}

		// Check immediately and then every 30 seconds
		checkForNew()
		const interval = setInterval(checkForNew, 30000)

		// Cleanup on unmount
		return () => clearInterval(interval)
	})

	setContext('notifications', {
		get all() {
			return notifications
		},
		get unreadCount() {
			return unreadCount
		},

		markAsRead(id) {
			const notification = notifications.find((n) => n.id === id)
			if (notification) {
				notification.read = true
			}
		},

		markAllAsRead() {
			for (const notification of notifications) {
				notification.read = true
			}
		},

		dismiss(id) {
			const index = notifications.findIndex((n) => n.id === id)
			if (index !== -1) {
				notifications.splice(index, 1)
			}
		}
	})
</script>

{@render children()}

Limpeza de Efeitos

Quando efeitos configuram assinaturas, temporizadores ou ouvintes de eventos, retorne uma função de limpeza:

<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let networkStatus = $state({ online: navigator.onLine })

	$effect(() => {
		function handleOnline() {
			networkStatus.online = true
		}

		function handleOffline() {
			networkStatus.online = false
		}

		window.addEventListener('online', handleOnline)
		window.addEventListener('offline', handleOffline)

		// Cleanup: runs before effect re-runs or component unmounts
		return () => {
			window.removeEventListener('online', handleOnline)
			window.removeEventListener('offline', handleOffline)
		}
	})

	setContext('network', {
		get isOnline() {
			return networkStatus.online
		},
		get isOffline() {
			return !networkStatus.online
		}
	})
</script>

{@render children()}

A função de limpeza previne vazamentos de memória e manipuladores de eventos obsoletos.

Múltiplos Effects para Separação de Responsabilidades

Não coloque tudo em um único effect. Separe as responsabilidades para maior clareza:

<script>
	import { setContext } from 'svelte'
	import { browser } from '$app/environment'

	let { children } = $props()

	let user = $state(null)
	let preferences = $state({ theme: 'light', fontSize: 16 })

	// Effect 1: Persist user to sessionStorage
	$effect(() => {
		if (!browser) return

		if (user) {
			sessionStorage.setItem('user', JSON.stringify(user))
		} else {
			sessionStorage.removeItem('user')
		}
	})

	// Effect 2: Persist preferences to localStorage
	$effect(() => {
		if (!browser) return
		localStorage.setItem('preferences', JSON.stringify(preferences))
	})

	// Effect 3: Apply theme to document
	$effect(() => {
		if (!browser) return
		document.documentElement.setAttribute('data-theme', preferences.theme)
	})

	// Effect 4: Apply font size to document
	$effect(() => {
		if (!browser) return
		document.documentElement.style.setProperty('--base-font-size', `${preferences.fontSize}px`)
	})

	// Effect 5: Analytics tracking
	$effect(() => {
		if (!browser || !user) return

		analytics.identify(user.id, {
			email: user.email,
			name: user.name
		})
	})

	setContext('app', {
		get user() {
			return user
		},
		get preferences() {
			return preferences
		}
		// ... methods
	})
</script>

{@render children()}

Cada effect tem uma única responsabilidade, tornando o código mais fácil de entender e manter.

Contexto em Arquivos .svelte.ts

Para contexto reutilizável e com tipagem segura, crie módulos em arquivos .svelte.ts. Isso separa a lógica de contexto dos componentes e possibilita uma melhor organização.

Um Módulo de Contador Completo

// lib/context/counter.svelte.ts
import { setContext, getContext, hasContext } from 'svelte'

// Use Symbol for collision-proof keys
const COUNTER_KEY = Symbol('counter')

// Type definitions
export interface CounterContext {
	readonly value: number
	readonly isAtMin: boolean
	readonly isAtMax: boolean
	increment(): void
	decrement(): void
	set(value: number): void
	reset(): void
}

export interface CounterOptions {
	initial?: number
	min?: number
	max?: number
	step?: number
}

// Creation function
export function createCounterContext(options: CounterOptions = {}): CounterContext {
	const { initial = 0, min = -Infinity, max = Infinity, step = 1 } = options

	// Internal state
	let count = $state(initial)

	// Derived values
	let isAtMin = $derived(count <= min)
	let isAtMax = $derived(count >= max)

	// Context API
	const context: CounterContext = {
		get value() {
			return count
		},
		get isAtMin() {
			return isAtMin
		},
		get isAtMax() {
			return isAtMax
		},

		increment() {
			if (count + step <= max) {
				count += step
			}
		},

		decrement() {
			if (count - step >= min) {
				count -= step
			}
		},

		set(value: number) {
			count = Math.max(min, Math.min(max, value))
		},

		reset() {
			count = initial
		}
	}

	return setContext(COUNTER_KEY, context)
}

// Getter with error handling
export function getCounterContext(): CounterContext {
	if (!hasContext(COUNTER_KEY)) {
		throw new Error(
			'Counter context not found. ' +
				'Wrap your component tree with CounterProvider ' +
				'or call createCounterContext().'
		)
	}
	return getContext(COUNTER_KEY)
}

// Optional getter for graceful handling
export function getCounterContextOrNull(): CounterContext | null {
	return hasContext(COUNTER_KEY) ? getContext(COUNTER_KEY) : null
}

// Check helper
export function hasCounterContext(): boolean {
	return hasContext(COUNTER_KEY)
}

Usando o Módulo

Crie um componente provedor:

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

	interface Props extends CounterOptions {
		children: import('svelte').Snippet
	}

	let { initial = 0, min, max, step, children }: Props = $props()

	createCounterContext({ initial, min, max, step })
</script>

{@render children()}

Use nos consumidores:

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

	const counter = getCounterContext()
</script>

<div class="counter">
	<button onclick={counter.decrement} disabled={counter.isAtMin}> − </button>

	<span>{counter.value}</span>

	<button onclick={counter.increment} disabled={counter.isAtMax}> + </button>
</div>

O TypeScript fornece autocomplete completo e verificação de tipos:

counter.value // ✅ number
counter.isAtMin // ✅ boolean
counter.increment() // ✅ void
counter.foo // ❌ Property 'foo' does not exist

Um Exemplo Mais Complexo: Contexto de Carrinho

// lib/context/cart.svelte.ts
import { setContext, getContext, hasContext } from 'svelte'
import { browser } from '$app/environment'

const CART_KEY = Symbol('cart')
const STORAGE_KEY = 'shopping_cart'

export interface CartItem {
	id: string
	name: string
	price: number
	quantity: number
}

export interface CartContext {
	readonly items: CartItem[]
	readonly itemCount: number
	readonly subtotal: number
	readonly isEmpty: boolean

	addItem(item: Omit<CartItem, 'quantity'>, quantity?: number): void
	removeItem(id: string): void
	updateQuantity(id: string, quantity: number): void
	clear(): void
}

export function createCartContext(): CartContext {
	// Load from storage
	function loadItems(): CartItem[] {
		if (!browser) return []
		try {
			const stored = localStorage.getItem(STORAGE_KEY)
			return stored ? JSON.parse(stored) : []
		} catch {
			return []
		}
	}

	// State
	let items = $state<CartItem[]>(loadItems())

	// Derived
	let itemCount = $derived(items.length)
	let subtotal = $derived(items.reduce((sum, item) => sum + item.price * item.quantity, 0))
	let isEmpty = $derived(items.length === 0)

	// Persistence effect
	$effect(() => {
		if (browser) {
			localStorage.setItem(STORAGE_KEY, JSON.stringify(items))
		}
	})

	// API
	const context: CartContext = {
		get items() {
			return items
		},
		get itemCount() {
			return itemCount
		},
		get subtotal() {
			return subtotal
		},
		get isEmpty() {
			return isEmpty
		},

		addItem(item, quantity = 1) {
			const existing = items.find((i) => i.id === item.id)
			if (existing) {
				existing.quantity += quantity
			} else {
				items.push({ ...item, quantity })
			}
		},

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

		updateQuantity(id, quantity) {
			const item = items.find((i) => i.id === id)
			if (item) {
				if (quantity <= 0) {
					this.removeItem(id)
				} else {
					item.quantity = quantity
				}
			}
		},

		clear() {
			items.length = 0
		}
	}

	return setContext(CART_KEY, context)
}

export function getCartContext(): CartContext {
	if (!hasContext(CART_KEY)) {
		throw new Error('Cart context not found. Wrap with CartProvider.')
	}
	return getContext(CART_KEY)
}

Organizando Módulos de Contexto

Uma estrutura típica para um aplicativo de médio porte:

src/lib/context/
├── cart.svelte.ts        # Shopping cart
├── auth.svelte.ts        # Authentication
├── theme.svelte.ts       # Theme preferences
├── notifications.svelte.ts  # Toast/notification system
├── types.ts              # Shared types
└── index.ts              # Public exports

O index.ts reexporta tudo para imports limpos:

// lib/context/index.ts
export * from './cart.svelte'
export * from './auth.svelte'
export * from './theme.svelte'
export * from './notifications.svelte'

Os consumidores importam o que precisam:

<script lang="ts">
	import { getCartContext, getAuthContext, getThemeContext } from '$lib/context'

	const cart = getCartContext()
	const auth = getAuthContext()
	const theme = getThemeContext()
</script>

Juntando Tudo

Vamos ver esses padrões combinados em um sistema de notificações realista:

// lib/context/notifications.svelte.ts
import { setContext, getContext, hasContext } from 'svelte'

const NOTIFICATIONS_KEY = Symbol('notifications')

export type NotificationType = 'info' | 'success' | 'warning' | 'error'

export interface Notification {
	id: string
	message: string
	type: NotificationType
	dismissible: boolean
	createdAt: number
}

export interface NotificationContext {
	readonly all: Notification[]
	readonly count: number
	readonly hasNotifications: boolean

	// Convenience methods
	info(message: string): string
	success(message: string): string
	warning(message: string): string
	error(message: string): string

	// Core methods
	add(message: string, options?: NotificationOptions): string
	dismiss(id: string): void
	dismissAll(): void
}

export interface NotificationOptions {
	type?: NotificationType
	duration?: number
	dismissible?: boolean
}

export function createNotificationContext(): NotificationContext {
	let notifications = $state<Notification[]>([])

	// Derived
	let count = $derived(notifications.length)
	let hasNotifications = $derived(count > 0)

	function generateId(): string {
		return `notification-${Date.now()}-${Math.random().toString(36).slice(2)}`
	}

	function addNotification(message: string, options: NotificationOptions = {}): string {
		const { type = 'info', duration = type === 'error' ? 0 : 5000, dismissible = true } = options

		const id = generateId()

		notifications.push({
			id,
			message,
			type,
			dismissible,
			createdAt: Date.now()
		})

		// Auto-dismiss if duration > 0
		if (duration > 0) {
			setTimeout(() => dismiss(id), duration)
		}

		return id
	}

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

	function dismissAll(): void {
		notifications.length = 0
	}

	const context: NotificationContext = {
		get all() {
			return notifications
		},
		get count() {
			return count
		},
		get hasNotifications() {
			return hasNotifications
		},

		info: (message) => addNotification(message, { type: 'info' }),
		success: (message) => addNotification(message, { type: 'success' }),
		warning: (message) => addNotification(message, { type: 'warning' }),
		error: (message) => addNotification(message, { type: 'error' }),

		add: addNotification,
		dismiss,
		dismissAll
	}

	return setContext(NOTIFICATIONS_KEY, context)
}

export function getNotificationContext(): NotificationContext {
	if (!hasContext(NOTIFICATIONS_KEY)) {
		throw new Error('Notification context not found. Wrap with NotificationProvider.')
	}
	return getContext(NOTIFICATIONS_KEY)
}

Provedor com UI:

<!-- NotificationProvider.svelte -->
<script lang="ts">
	import { createNotificationContext } from '$lib/context/notifications.svelte'
	import { fly, fade } from 'svelte/transition'

	let { children } = $props()

	const notifications = createNotificationContext()
</script>

{@render children()}

<!-- Notification toast container -->
{#if notifications.hasNotifications}
	<div class="notification-container" role="region" aria-label="Notifications">
		{#each notifications.all as notification (notification.id)}
			<div
				class="notification notification-{notification.type}"
				role="alert"
				in:fly={{ y: 20, duration: 200 }}
				out:fade={{ duration: 150 }}
			>
				<span class="message">{notification.message}</span>

				{#if notification.dismissible}
					<button
						class="dismiss"
						onclick={() => notifications.dismiss(notification.id)}
						aria-label="Dismiss"
					>
						×
					</button>
				{/if}
			</div>
		{/each}
	</div>
{/if}

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

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

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

	.dismiss {
		padding: 0.25rem;
		border: none;
		background: none;
		font-size: 1.25rem;
		cursor: pointer;
		opacity: 0.5;
	}

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

Uso em toda a aplicação:

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

	const notify = getNotificationContext()

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

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

{#if notify.hasNotifications}
	<span class="badge">{notify.count}</span>
{/if}

Referência Rápida

Padrão	Quando Usar	Exemplo
Getters	Sempre para leitura de estado	`get value() { return count }`
Methods	Para mutações com validação	`increment() { if (canIncrement) count++ }`
$derived	Valores computados a partir do estado	`let total = $derived(subtotal + tax)`
$effect	Efeitos colaterais (persistência, sincronização)	`$effect(() => localStorage.setItem(key, value))`
Symbol keys	Chaves de contexto à prova de colisão	`const KEY = Symbol('feature')`
.svelte.ts	Módulos de contexto tipados reutilizáveis	`export function createContext()`

Conclusão

Os padrões de contexto reativo representam a maturação do gerenciamento de estado no Svelte 5. Os fundamentos—objetos $state e a regra "mutate, don't reassign"—fornecem a base. Os padrões neste artigo—getters, $derived, $effect e módulos .svelte.ts—transformam essa base em uma arquitetura de qualidade para produção.

A progressão é natural: você começa expondo o estado bruto, então percebe que precisa de encapsulamento (getters). Você se vê computando os mesmos valores repetidamente e descobre que o $derived lida com isso automaticamente. Você precisa de persistência ou sincronização, e o $effect fornece o gancho reativo. Por fim, você quer reutilização e tipagem segura, e os módulos .svelte.ts entregam isso.

O que torna esses padrões poderosos é a forma como eles se compõem. Um sistema de notificações pode usar todos eles: getters para count e hasNotifications, $derived para filtrar por tipo, $effect para temporizadores de auto-descarte e um módulo .svelte.ts para a API tipada completa. Cada padrão resolve um problema bem, e juntos resolvem problemas complexos com elegância.

O investimento em aprender esses padrões rende dividendos em cada contexto que você construir. Suas APIs se tornam mais limpas, seu código mais fácil de manter, e seus consumidores—seja você mesmo no próximo mês ou um colega de equipe no próximo ano—vão agradecer pela clareza.

Principais Conclusões

Getters garantem valores atuais—sempre exponha o estado reativo por meio de get value() { return state } em vez de capturar valores no momento da criação
Getters possibilitam encapsulamento—a implementação interna pode mudar sem quebrar os consumidores, desde que a interface do getter permaneça a mesma
$derived lida com valores computados—o Svelte rastreia automaticamente as dependências e recalcula quando elas mudam, eliminando a lógica de atualização manual
Valores derivados podem ser encadeados—subtotal depende de items, total depende de subtotal e shipping—o Svelte gerencia o grafo de dependências
$effect gerencia efeitos colaterais—use para persistência, sincronização externa, atualizações do DOM e analytics; retorne funções de limpeza para listeners e temporizadores
Separe responsabilidades em múltiplos effects—cada effect deve ter uma única responsabilidade para clareza e facilidade de manutenção
Módulos .svelte.ts possibilitam reutilização—crie módulos de contexto tipados com chaves Symbol, funções de criação e getters tipados para APIs profissionais
Exporte APIs completas—forneça funções de criação, getters obrigatórios e opcionais, e interfaces TypeScript claras

O Que Vem a Seguir

Leve o encapsulamento adiante com Contexto Baseado em Classes, onde as classes TypeScript se combinam com runes para um gerenciamento de estado poderoso, campos privados e padrões de herança.

Veja Também

Documentação Oficial

$state — Estado reativo
$derived — Valores computados
$effect — Efeitos colaterais
Arquivos .svelte.ts — Runes em TypeScript