Da Mecânica à Maestria

Ao longo desta série, exploramos a mecânica da API de Contexto do Svelte—como fornecer contexto, consumi-lo, lidar com aninhamento profundo, torná-lo reativo com runes e aplicá-lo a cenários do mundo real, como gerenciamento de temas e compartilhamento de dados complexos. Agora você entende como o contexto funciona.

Este artigo muda o foco para como usar o contexto bem. Vamos estabelecer padrões profissionais que tornam o código de contexto sustentável, testável e escalável. Não são preferências de estilo arbitrárias—são lições aprendidas na construção e manutenção de grandes aplicações Svelte onde o contexto desempenha um papel arquitetural central.

Ao seguir essas práticas, você escreverá código de contexto que:

É imediatamente compreensível para outros desenvolvedores
Detecta erros em tempo de compilação em vez de tempo de execução
Pode ser testado isoladamente
Tem bom desempenho mesmo em aplicações complexas
Escala graciosamente à medida que sua aplicação cresce

Seja você um iniciante querendo estabelecer bons hábitos desde o início, ou um desenvolvedor experiente buscando refinar seus padrões, este guia fornece a base para o uso profissional de contexto.

O Framework de Decisão

Antes de mergulhar nos detalhes de implementação, você precisa de um modelo mental para decidir quando usar contexto versus outros padrões. Este framework de decisão vai te salvar do erro comum de superengenheirar problemas simples ou subengenheiar problemas complexos.

┌─────────────────────────────────────────────────────────────────┐
│                    State/Data Decision Tree                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Q1: Is it needed by just one child component?                 │
│      YES → Use props                                            │
│      NO  → Continue to Q2                                       │
│                                                                 │
│  Q2: Is it needed by siblings (not ancestors/descendants)?     │
│      YES → Lift state to common ancestor, use props             │
│      NO  → Continue to Q3                                       │
│                                                                 │
│  Q3: Is it needed by deeply nested descendants?                │
│      YES → Continue to Q4                                       │
│      NO  → Use props (probably shallow)                         │
│                                                                 │
│  Q4: Is it "ambient" data (theme, locale, auth, tenant)?       │
│      YES → Use context                                          │
│      NO  → Continue to Q5                                       │
│                                                                 │
│  Q5: Is it feature-boundary state (cart, form wizard)?         │
│      YES → Use context with provider component                  │
│      NO  → Continue to Q6                                       │
│                                                                 │
│  Q6: Is it truly global (needs to work outside component tree)?│
│      YES → Consider stores (but verify not SSR-unsafe)         │
│      NO  → Context is probably right                            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Este framework encapsula a percepção central: o contexto preenche um nicho específico—estado compartilhado com escopo de subárvore—e se destaca quando usado adequadamente. Não é um substituto para props, stores ou funções de carregamento, mas um complemento a eles.

Convenções de Nomenclatura

Nomenclatura consistente torna o código previsível. Quando os desenvolvedores conseguem adivinhar corretamente os nomes de funções e variáveis, eles passam menos tempo lendo documentação e pesquisando bases de código. Esta seção estabelece os padrões de nomenclatura que bases de código Svelte profissionais seguem.

Nomenclatura de Chaves de Contexto

Se estiver usando chaves de string, adote um padrão de nomenclatura consistente em toda a sua aplicação:

// ✅ Good: Descriptive, lowercase with hyphens
setContext('user-auth', authContext)
setContext('shopping-cart', cartContext)
setContext('theme-settings', themeContext)
setContext('notification-manager', notificationContext)

// ✅ Good: Namespaced for libraries or large apps
setContext('myapp:auth', authContext)
setContext('myapp:cart', cartContext)
setContext('acme-ui:modal', modalContext)

// ❌ Avoid: Vague or inconsistent
setContext('data', authContext) // Too vague—data for what?
setContext('UserAuth', authContext) // Inconsistent casing
setContext('ctx', cartContext) // Cryptic abbreviation
setContext('Theme', themeContext) // PascalCase is for components
setContext('THEME', themeContext) // SCREAMING_CASE is confusing

Para aplicações em produção, prefira Symbols ou createContext para eliminar completamente os riscos de colisão. Chaves de string funcionam bem para aplicações pequenas, mas chaves Symbol garantem unicidade—dois Symbols jamais são iguais, mesmo com a mesma descrição:

// ✅ Best: Symbols for guaranteed uniqueness
const AUTH_KEY = Symbol('auth')
const CART_KEY = Symbol('cart')

// ✅ Best: createContext for type safety (Svelte 5.40+)
const [getAuth, setAuth] = createContext<AuthContext>()

Estabilidade de Chaves de Contexto

As chaves de contexto devem ser estáveis durante toda a vida útil da sua aplicação. Mudar chaves quebra os consumidores, às vezes silenciosamente. Considere este padrão problemático:

// ❌ Key could change between versions
setContext('themeV2', theme) // Was 'theme' in v1

// Every consumer needs to update:
getContext('themeV2') // Breaking change!

Em vez disso, centralize as chaves e as esconda por trás de funções de acesso:

// src/lib/context-keys.ts
export const THEME_KEY = Symbol('theme')
export const AUTH_KEY = Symbol('auth')
export const CART_KEY = Symbol('cart')

Ou melhor, forneça funções de acesso tipadas que escondam a chave completamente:

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

const KEY = Symbol('theme')

export interface ThemeContext {
	/* ... */
}

export function setThemeContext(ctx: ThemeContext): void {
	setContext(KEY, ctx)
}

export function getThemeContext(): ThemeContext {
	return getContext<ThemeContext>(KEY)
}

Agora os consumidores nunca tocam diretamente na chave, e você pode mudar a implementação sem quebrar ninguém:

<script>
	import { getThemeContext } from '$lib/theme/context.js'

	const theme = getThemeContext()
</script>

Este padrão oculta a implementação da chave, fornece segurança de tipos, permite mudanças de chave sem quebrar consumidores e documenta o tipo de retorno esperado.

Padrões de Nomenclatura de Funções

Estabeleça nomenclatura consistente para funções relacionadas ao contexto e mantenha-a em toda a sua base de código:

// Creation functions: create[Name]Context
export function createAuthContext(options: AuthOptions): AuthContext
export function createCartContext(initialItems?: CartItem[]): CartContext
export function createThemeContext(defaultTheme?: ThemeName): ThemeContext

// Getter functions: get[Name]Context
export function getAuthContext(): AuthContext
export function getCartContext(): CartContext

// Alternative: use* prefix (familiar to React developers, works well in Svelte)
export function useAuth(): AuthContext
export function useCart(): CartContext
export function useTheme(): ThemeContext

// Checker functions: has[Name]Context
export function hasAuthContext(): boolean
export function hasCartContext(): boolean

Escolha um padrão e mantenha a consistência. Misturar getAuthContext com useCart cria fricção cognitiva e torna sua base de código mais difícil de navegar.

Padrões de Nomenclatura de Arquivos

Nomeie os arquivos para refletir seu conteúdo e indicar se usam runes:

lib/context/
├── auth.svelte.ts           # Auth context (uses runes)
├── auth.ts                  # Auth context (no runes needed)
├── cart.svelte.ts           # Cart context with reactive state
├── theme.svelte.ts          # Theme context with effects
├── types.ts                 # Shared types for all contexts
└── index.ts                 # Public exports

Use a extensão .svelte.ts quando o arquivo usar runes ($state, $derived, $effect). Isso não é apenas convenção—o Svelte requer isso para o processamento de runes. Errar nisso leva a erros crípticos que desperdiçam tempo de depuração.

Nomenclatura de Componentes Provider

Componentes provider devem indicar claramente o que fornecem:

// ✅ Good: Clear purpose
AuthProvider.svelte
CartProvider.svelte
ThemeProvider.svelte
NotificationProvider.svelte

// ✅ Good: Composition component
AppProviders.svelte // Composes multiple providers
Providers.svelte // Alternative shorter name

// ❌ Avoid: Unclear names
Provider.svelte // Which provider?
Context.svelte // Too generic
Wrapper.svelte // Doesn't indicate purpose

Nomes de Tipos

Siga as convenções do TypeScript para nomenclatura de tipos:

// ✅ Type naming conventions
interface ThemeContext {
	/* ... */
}
interface AuthContext {
	/* ... */
}
interface CartContext {
	/* ... */
}

// Alternative: "*State" for internal state, "*Context" for exposed API
interface ThemeState {
	/* ... */
} // Internal implementation
interface ThemeContext {
	/* ... */
} // What consumers receive

Organização de Arquivos

A forma como você organiza os arquivos de contexto afeta a descobribilidade e a manutenibilidade. A escolha certa depende do tamanho da sua aplicação, da estrutura da equipe e de como seus contextos se relacionam com as funcionalidades.

Padrão 1: Diretório de Contexto Centralizado

Todo o contexto em um único local:

src/lib/
└── context/
    ├── auth.svelte.ts
    ├── cart.svelte.ts
    ├── theme.svelte.ts
    ├── notifications.svelte.ts
    ├── types.ts
    └── index.ts

Este padrão oferece várias vantagens. Todos os contextos são fáceis de encontrar em um único lugar, e as importações se tornam simples e consistentes. Você obtém uma visão clara do estado em toda a aplicação, sendo ideal para aplicações pequenas a médias onde os contextos são verdadeiramente compartilhados entre funcionalidades.

O arquivo index.ts exporta tudo que os consumidores precisam:

// lib/context/index.ts

// Auth context
export {
	createAuthContext,
	getAuthContext,
	hasAuthContext,
	type AuthContext,
	type User
} from './auth.svelte'

// Cart context
export {
	createCartContext,
	getCartContext,
	hasCartContext,
	type CartContext,
	type CartItem
} from './cart.svelte'

// Theme context
export {
	createThemeContext,
	getThemeContext,
	hasThemeContext,
	type ThemeContext,
	type ThemeMode
} from './theme.svelte'

// Re-export all types
export * from './types'

Padrão 2: Contexto Colocado com a Funcionalidade

O contexto fica junto com sua funcionalidade:

src/lib/features/
├── auth/
│   ├── context.svelte.ts     # Auth context
│   ├── AuthProvider.svelte   # Provider component
│   ├── LoginForm.svelte      # Feature components
│   ├── LogoutButton.svelte
│   ├── UserMenu.svelte
│   └── index.ts              # Public exports
├── cart/
│   ├── context.svelte.ts
│   ├── CartProvider.svelte
│   ├── CartDrawer.svelte
│   ├── CartIcon.svelte
│   ├── AddToCartButton.svelte
│   └── index.ts
└── theme/
    ├── context.svelte.ts
    ├── ThemeProvider.svelte
    ├── ThemeToggle.svelte
    └── index.ts

Este padrão mantém o contexto próximo de seus consumidores, tornando as funcionalidades autocontidas e portáteis. Limites claros de propriedade emergem naturalmente. Escala bem para grandes aplicações e equipes, e facilita entender o que uma funcionalidade precisa de relance.

Cada funcionalidade expõe uma API pública limpa através de seu index.ts:

// lib/features/auth/index.ts

// Context (internal implementation hidden)
export { createAuthContext, getAuthContext } from './context.svelte'
export type { AuthContext, User } from './context.svelte'

// Provider
export { default as AuthProvider } from './AuthProvider.svelte'

// Components
export { default as LoginForm } from './LoginForm.svelte'
export { default as LogoutButton } from './LogoutButton.svelte'
export { default as UserMenu } from './UserMenu.svelte'

Padrão 3: Abordagem Híbrida

Contexto central/compartilhado centralizado, contexto específico de funcionalidade colocado junto:

src/lib/
├── context/                    # Application-wide context
│   ├── theme.svelte.ts        # Everyone needs theme
│   ├── locale.svelte.ts       # Internationalization
│   ├── feature-flags.svelte.ts
│   └── index.ts
└── features/
    ├── auth/                   # Feature-specific context
    │   ├── context.svelte.ts
    │   └── ...
    ├── cart/
    │   ├── context.svelte.ts
    │   └── ...
    └── checkout/
        ├── context.svelte.ts   # Only used in checkout flow
        └── ...

Use este guia de decisão para escolher o local correto:

Tipo de Contexto	Local	Raciocínio
Tema, locale, feature flags	Centralizado	Usado em toda a aplicação
Auth	Qualquer	Depende de quão específicos são seus componentes de auth
Carrinho de compras	Feature	A lógica do carrinho é específica da feature
Wizard de checkout	Feature	Usado apenas no fluxo de checkout
Gerenciadores de modal/toast	Centralizado	Usado por muitas features

Segurança de Tipos

O TypeScript transforma o contexto de um mistério em tempo de execução para um contrato em tempo de compilação. Invista em tipagem adequada — isso gera dividendos na experiência do desenvolvedor e na prevenção de bugs todos os dias.

Defina Interfaces Explícitas

Nunca confie na inferência de tipos para APIs de contexto. Interfaces explícitas servem como documentação, habilitam melhor suporte de IDE e detectam erros cedo:

// ✅ Good: Explicit interface
export interface AuthContext {
	readonly user: User | null
	readonly isAuthenticated: boolean
	readonly isLoading: boolean
	readonly error: string | null
	login(email: string, password: string): Promise<void>
	logout(): Promise<void>
	refresh(): Promise<void>
}

export interface User {
	id: string
	email: string
	name: string
	avatar?: string
	role: 'admin' | 'user' | 'guest'
	permissions: string[]
}

// ❌ Avoid: Implicit types
export function createAuthContext() {
	let user = $state(null) // What's the type of user?
	// ...
	return {
		get user() {
			return user
		},
		login(email, password) {
			/* ... */
		} // What are the param types?
	}
}

A versão com interface explícita diz aos desenvolvedores exatamente com o que estão trabalhando antes mesmo de lerem a implementação.

Use `createContext` para Acesso com Segurança de Tipos

O Svelte 5.40+ fornece createContext para segurança de tipos automática:

// lib/context/auth.svelte.ts
import { createContext } from 'svelte'

export interface AuthContext {
	readonly user: User | null
	readonly isAuthenticated: boolean
	login(email: string, password: string): Promise<void>
	logout(): Promise<void>
}

// Type is automatically inferred for both getter and setter
export const [getAuth, setAuth] = createContext<AuthContext>()

Os consumidores obtêm IntelliSense completo sem nenhum esforço extra:

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

	const auth = getAuth()

	auth.user?.name // ✅ TypeScript knows this is string | undefined
	auth.isAuthenticated // ✅ TypeScript knows this is boolean
	auth.login('a', 'b') // ✅ TypeScript validates parameters
	auth.foo // ❌ TypeScript error: Property 'foo' does not exist
</script>

Funções Wrapper com Tipos

Se não estiver usando createContext, crie funções wrapper tipadas que forneçam os mesmos benefícios:

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

const AUTH_KEY = Symbol('auth')

export interface AuthContext {
	readonly user: User | null
	readonly isAuthenticated: boolean
	login(email: string, password: string): Promise<void>
	logout(): Promise<void>
}

export function createAuthContext(): AuthContext {
	let user = $state<User | null>(null)
	let isLoading = $state(false)

	const context: AuthContext = {
		get user() {
			return user
		},
		get isAuthenticated() {
			return user !== null
		},

		async login(email: string, password: string) {
			isLoading = true
			try {
				const response = await fetch('/api/auth/login', {
					method: 'POST',
					body: JSON.stringify({ email, password })
				})
				user = await response.json()
			} finally {
				isLoading = false
			}
		},

		async logout() {
			await fetch('/api/auth/logout', { method: 'POST' })
			user = null
		}
	}

	return setContext(AUTH_KEY, context)
}

// Typed getter - no casting needed at call sites
export function getAuthContext(): AuthContext {
	const context = getContext<AuthContext>(AUTH_KEY)
	if (!context) {
		throw new Error('Auth context not found. Wrap your app in AuthProvider.')
	}
	return context
}

export function hasAuthContext(): boolean {
	return hasContext(AUTH_KEY)
}

Utilitários de Contexto Genéricos

Crie utilitários reutilizáveis para padrões comuns a fim de reduzir o boilerplate:

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

/**
 * Creates a type-safe context with getter, setter, and checker.
 * Alternative to createContext for more control.
 */
export function defineContext<T>(name: string) {
	const key = Symbol(name)

	return {
		set(value: T): T {
			return setContext(key, value)
		},

		get(): T {
			if (!hasContext(key)) {
				throw new Error(
					`${name} context not found. ` +
						`Ensure this component is wrapped in the appropriate provider.`
				)
			}
			return getContext<T>(key)
		},

		getOptional(): T | undefined {
			return hasContext(key) ? getContext<T>(key) : undefined
		},

		has(): boolean {
			return hasContext(key)
		}
	}
}

O uso torna-se limpo e consistente:

// lib/context/cart.svelte.ts
import { defineContext } from './utils'

export interface CartContext {
	readonly items: CartItem[]
	readonly total: number
	addItem(product: Product, quantity?: number): void
	removeItem(productId: string): void
	clear(): void
}

const cartContext = defineContext<CartContext>('Cart')

export const setCartContext = cartContext.set
export const getCartContext = cartContext.get
export const hasCartContext = cartContext.has

Princípios de Design de API

Uma API de contexto bem projetada facilita a vida dos consumidores e previne uso indevido. Esses princípios se aplicam tanto se você está construindo contexto para sua própria aplicação quanto para uma biblioteca compartilhada.

Exponha Getters, Não Estado Bruto

Sempre use getters para expor o estado. Isso fornece encapsulamento, garante que os consumidores recebam valores reativos atualizados e permite refatoração futura:

// ❌ Exposing raw state - consumers get a snapshot, not reactive
let count = $state(0)
setContext('counter', count)

// ❌ Exposing state object directly - consumers can mutate arbitrarily
let state = $state({ count: 0, step: 1 })
setContext('counter', state)

// ✅ Exposing via getters - controlled, reactive access
let count = $state(0)
let step = $state(1)

setContext('counter', {
	get count() {
		return count
	},
	get step() {
		return step
	},
	increment() {
		count += step
	},
	decrement() {
		count -= step
	}
})

Getters garantem valores atualizados, permitem refatoração futura sem quebrar consumidores e habilitam validação ou transformação antes de retornar valores.

Forneça Actions, Não Apenas Estado

Boas APIs incluem tanto o estado quanto as operações que o modificam. Não faça os consumidores descobrirem como atualizar o estado corretamente:

// ❌ State only - consumers must figure out how to update
setContext('user', {
	get data() {
		return user
	}
})

// ✅ State + actions - clear API for updates
setContext('user', {
	get data() {
		return user
	},
	get isAuthenticated() {
		return user !== null
	},

	async updateProfile(updates: Partial<User>) {
		const response = await fetch('/api/user', {
			method: 'PATCH',
			body: JSON.stringify(updates)
		})
		user = await response.json()
	},

	async uploadAvatar(file: File) {
		const formData = new FormData()
		formData.append('avatar', file)
		const response = await fetch('/api/user/avatar', {
			method: 'POST',
			body: formData
		})
		const { avatarUrl } = await response.json()
		user = { ...user, avatar: avatarUrl }
	}
})

Inclua Estados de Loading e Erro

Operações assíncronas devem expor seu status. Os consumidores não deveriam ter que rastrear estados de loading e erro por conta própria:

interface DataContext<T> {
	readonly data: T | null
	readonly isLoading: boolean
	readonly error: Error | null
	readonly isError: boolean
	readonly isSuccess: boolean
	refresh(): Promise<void>
}

function createDataContext<T>(fetcher: () => Promise<T>): DataContext<T> {
	let data = $state<T | null>(null)
	let isLoading = $state(true)
	let error = $state<Error | null>(null)

	async function load() {
		isLoading = true
		error = null
		try {
			data = await fetcher()
		} catch (e) {
			error = e instanceof Error ? e : new Error(String(e))
		} finally {
			isLoading = false
		}
	}

	// Initial load
	load()

	return setContext('data', {
		get data() {
			return data
		},
		get isLoading() {
			return isLoading
		},
		get error() {
			return error
		},
		get isError() {
			return error !== null
		},
		get isSuccess() {
			return data !== null && !error
		},
		refresh: load
	})
}

Use Tipos de Resultado para Operações Falíveis

Para operações que podem falhar, retorne objetos de resultado em vez de lançar exceções. Isso torna o tratamento de erros explícito e combinável:

interface Result<T, E = Error> {
	success: boolean
	data?: T
	error?: E
}

interface CartContext {
	// ...state getters...

	addItem(product: Product, quantity?: number): Result<CartItem>
	removeItem(productId: string): Result<void>
	applyDiscount(code: string): Promise<Result<Discount, DiscountError>>
}

function createCartContext(): CartContext {
	let items = $state<CartItem[]>([])

	return setContext('cart', {
		get items() {
			return items
		},

		addItem(product, quantity = 1) {
			// Validate stock
			if (quantity > product.stockCount) {
				return {
					success: false,
					error: new Error(`Only ${product.stockCount} items available`)
				}
			}

			// Add item
			const item = { ...product, quantity }
			items.push(item)

			return { success: true, data: item }
		},

		async applyDiscount(code) {
			const response = await fetch(`/api/discounts/${code}`)

			if (!response.ok) {
				const error = await response.json()
				return {
					success: false,
					error: { code: 'INVALID_CODE', message: error.message }
				}
			}

			const discount = await response.json()
			return { success: true, data: discount }
		}
	})
}

Os consumidores tratam os resultados explicitamente, tornando os casos de erro visíveis:

<script>
	const cart = getCartContext()

	async function handleAddToCart() {
		const result = cart.addItem(product)

		if (result.success) {
			toast.success(`Added ${product.name} to cart`)
		} else {
			toast.error(result.error.message)
		}
	}
</script>

Mantenha as APIs Mínimas e Estáveis

Comece pequeno. Você sempre pode adicionar a uma API de contexto, mas remover é uma mudança que quebra compatibilidade:

// ✅ Start minimal
interface CartContext {
	readonly items: CartItem[]
	readonly total: number
	addItem: (product: Product) => void
	removeItem: (id: string) => void
}

// Later, add features additively
interface CartContext {
	// ... existing properties unchanged ...
	applyCoupon: (code: string) => Promise<boolean> // New feature!
}

Considerações de Performance

O contexto foi projetado para ser performático, mas padrões de uso inadequados ainda podem causar problemas. Entender esses padrões ajuda a evitar armadilhas de performance antes que se tornem problemas.

Meça Antes de Otimizar

Buscas de contexto são rápidas — tipicamente microssegundos. Antes de aplicar padrões de otimização, verifique se você realmente tem um problema de performance:

// Simple timing for context-heavy operations
console.time('render-cycle')
// ... component renders
console.timeEnd('render-cycle')

// Use browser DevTools Performance tab for detailed analysis
// Look for long tasks, excessive re-renders, or memory growth

A maioria das aplicações nunca precisa de otimizações específicas de contexto. Os padrões abaixo abordam casos extremos — aplique-os apenas quando o profiling revelar o contexto como um gargalo real, não como otimização prematura.

Evite Atualizações Frequentes de Contexto

As buscas de contexto acontecem uma vez durante a inicialização do componente. No entanto, se o valor do seu contexto muda com frequência e muitos componentes o leem, você pode observar impactos na performance:

// ❌ Potentially problematic: Updates every mouse move
function createMouseContext() {
	let position = $state({ x: 0, y: 0 })

	$effect(() => {
		function handleMove(e: MouseEvent) {
			position.x = e.clientX
			position.y = e.clientY
		}
		window.addEventListener('mousemove', handleMove)
		return () => window.removeEventListener('mousemove', handleMove)
	})

	return setContext('mouse', {
		get position() {
			return position
		}
	})
}

Se muitos componentes consomem esse contexto, cada um reagirá a cada movimento do mouse. A solução é throttle nas atualizações ou dividir o contexto:

<!-- MouseProvider.svelte -->
<script>
	import { setContext } from 'svelte'
	import { throttle } from 'lodash-es'

	let { children } = $props()

	let position = $state({ x: 0, y: 0 })

	$effect(() => {
		const handleMove = throttle((e) => {
			position.x = e.clientX
			position.y = e.clientY
		}, 16) // ~60fps

		window.addEventListener('mousemove', handleMove)
		return () => {
			handleMove.cancel()
			window.removeEventListener('mousemove', handleMove)
		}
	})

	setContext('mouse', {
		get position() {
			return position
		}
	})
</script>

{@render children()}

A rune $effect geralmente não deveria atribuir estado — é para isso que serve o $derived. No entanto, handlers de eventos externos (eventos DOM, timers, mensagens WebSocket) são exceções legítimas. Esses eventos se originam fora do sistema de reatividade do Svelte e precisam empurrar valores para o estado.

O exemplo de rastreamento do mouse acima é válido porque:

Movimentos do mouse são eventos DOM externos, não derivados de outro estado
Não há como expressar "posição atual do mouse" como um valor $derived
O effect limpa corretamente seu event listener

Quando você vir $effect atribuindo estado, pergunte: "Isto está respondendo a algo externo?" Se sim, é apropriado. Se o valor pudesse ser computado a partir de outro estado reativo, use $derived em vez disso.

Divida Contextos Grandes

Se você tem um objeto de contexto grande onde diferentes componentes precisam de partes diferentes, considere dividi-lo:

// ❌ Monolithic context: All consumers react to any change
setContext('app', {
	get user() {
		return user
	},
	get theme() {
		return theme
	},
	get cart() {
		return cart
	},
	get notifications() {
		return notifications
	}
	// ... many more properties
})

// ✅ Split contexts: Components only subscribe to what they need
setContext('user', {
	get data() {
		return user
	}
})
setContext('theme', {
	get mode() {
		return theme
	}
})
setContext('cart', {
	get items() {
		return cartItems
	}
})
setContext('notifications', {
	get list() {
		return notifications
	}
})

Use $derived para Valores Computados

Compute valores derivados uma vez no provedor, não repetidamente nos consumidores:

// ✅ Good: Compute once in provider
function createCartContext() {
	let items = $state<CartItem[]>([])

	// Computed once, cached until items change
	let subtotal = $derived(items.reduce((sum, item) => sum + item.price * item.quantity, 0))

	let tax = $derived(subtotal * 0.08)
	let total = $derived(subtotal + tax)

	return setContext('cart', {
		get items() {
			return items
		},
		get subtotal() {
			return subtotal
		},
		get tax() {
			return tax
		},
		get total() {
			return total
		}
	})
}

// ❌ Avoid: Consumers compute the same value repeatedly
// In Consumer1.svelte
const cart = getCartContext()
let total = $derived(cart.items.reduce((sum, i) => sum + i.price * i.quantity, 0) * 1.08)

// In Consumer2.svelte - same computation again!
const cart = getCartContext()
let total = $derived(cart.items.reduce((sum, i) => sum + i.price * i.quantity, 0) * 1.08)

Inicialização Preguiçosa

Para operações custosas, inicialize de forma preguiçosa:

function createApiContext() {
	// Don't create client immediately
	let client: ApiClient | null = null

	function getClient(): ApiClient {
		// Create on first access
		if (!client) {
			client = new ApiClient({
				baseUrl: '/api',
				timeout: 10000
			})
		}
		return client
	}

	return setContext('api', {
		get client() {
			return getClient()
		}
	})
}

Testando Contexto

Um contexto bem projetado é um contexto testável. Os padrões nesta seção garantem que a lógica do seu contexto possa ser testada isoladamente e que os componentes que consomem contexto possam ser testados de forma eficaz.

Testando a Lógica de Contexto em Isolamento

Extraia a lógica de contexto para arquivos .svelte.ts para que você possa testá-la sem renderizar componentes:

// lib/context/counter.svelte.ts
export interface CounterContext {
	readonly value: number
	readonly isAtMax: boolean
	readonly isAtMin: boolean
	increment(): void
	decrement(): void
	reset(): void
}

export function createCounter(initial = 0, min = 0, max = 100): CounterContext {
	let value = $state(initial)

	return {
		get value() {
			return value
		},
		get isAtMax() {
			return value >= max
		},
		get isAtMin() {
			return value <= min
		},

		increment() {
			if (value < max) value++
		},

		decrement() {
			if (value > min) value--
		},

		reset() {
			value = initial
		}
	}
}

Teste a lógica diretamente:

// lib/context/counter.svelte.test.ts
import { describe, it, expect } from 'vitest'
import { createCounter } from './counter.svelte'

describe('createCounter', () => {
	it('initializes with default value', () => {
		const counter = createCounter()
		expect(counter.value).toBe(0)
	})

	it('initializes with custom value', () => {
		const counter = createCounter(50)
		expect(counter.value).toBe(50)
	})

	it('increments value', () => {
		const counter = createCounter(0)
		counter.increment()
		expect(counter.value).toBe(1)
	})

	it('respects max boundary', () => {
		const counter = createCounter(99, 0, 100)
		counter.increment()
		expect(counter.value).toBe(100)
		counter.increment()
		expect(counter.value).toBe(100) // Stays at max
		expect(counter.isAtMax).toBe(true)
	})

	it('respects min boundary', () => {
		const counter = createCounter(1, 0, 100)
		counter.decrement()
		expect(counter.value).toBe(0)
		counter.decrement()
		expect(counter.value).toBe(0) // Stays at min
		expect(counter.isAtMin).toBe(true)
	})

	it('resets to initial value', () => {
		const counter = createCounter(25)
		counter.increment()
		counter.increment()
		expect(counter.value).toBe(27)
		counter.reset()
		expect(counter.value).toBe(25)
	})
})

Testando Componentes Provedores

Teste provedores renderizando-os com consumidores de teste:

// lib/context/CounterProvider.test.ts
import { render, screen } from '@testing-library/svelte'
import userEvent from '@testing-library/user-event'
import { describe, it, expect } from 'vitest'
import CounterTestWrapper from './CounterTestWrapper.svelte'

describe('CounterProvider', () => {
	it('provides counter context to children', async () => {
		render(CounterTestWrapper)

		expect(screen.getByTestId('value')).toHaveTextContent('0')

		await userEvent.click(screen.getByRole('button', { name: /increment/i }))

		expect(screen.getByTestId('value')).toHaveTextContent('1')
	})

	it('respects initial prop', () => {
		render(CounterTestWrapper, { props: { initial: 42 } })

		expect(screen.getByTestId('value')).toHaveTextContent('42')
	})
})

<!-- CounterTestWrapper.svelte -->
<script>
	import CounterProvider from './CounterProvider.svelte'
	import CounterConsumer from './CounterConsumer.test.svelte'

	let { initial = 0 } = $props()
</script>

<CounterProvider {initial}>
	<CounterConsumer />
</CounterProvider>

<!-- CounterConsumer.test.svelte -->
<script>
	import { getCounterContext } from './counter.svelte'

	const counter = getCounterContext()
</script>

<span data-testid="value">{counter.value}</span>
<button onclick={counter.increment}>Increment</button>
<button onclick={counter.decrement}>Decrement</button>

Simulando Contexto para Testes Unitários

Às vezes você quer testar um componente com um contexto simulado em vez do provedor real:

// lib/context/test-utils.ts
import { setContext } from 'svelte'
import { vi } from 'vitest'

const AUTH_KEY = Symbol('auth')

export function mockAuthContext(overrides: Partial<AuthContext> = {}): AuthContext {
	const defaultContext: AuthContext = {
		user: null,
		isAuthenticated: false,
		isLoading: false,
		error: null,
		login: vi.fn(),
		logout: vi.fn(),
		refresh: vi.fn()
	}

	const context = { ...defaultContext, ...overrides }
	setContext(AUTH_KEY, context)
	return context
}

<!-- MockProvider.svelte for testing -->
<script lang="ts">
	import { mockAuthContext } from '$lib/context/test-utils'
	import type { Snippet } from 'svelte'
	import type { User } from '$lib/context/auth.svelte'

	interface Props {
		user?: User | null
		isAuthenticated?: boolean
		children: Snippet
	}

	let { user = null, isAuthenticated = false, children }: Props = $props()

	// Set context once at initialization.
	// Test utilities don't need reactive prop updates.
	mockAuthContext({ user, isAuthenticated })
</script>

{@render children()}

Crie um Wrapper de Teste Genérico

Para testar múltiplos contextos de uma vez:

<!-- tests/ContextWrapper.svelte -->
<script lang="ts">
	import { setContext } from 'svelte'
	import type { Snippet } from 'svelte'

	interface Props {
		contexts: Record<string | symbol, unknown>
		children: Snippet
	}

	const props: Props = $props()

	// Context must be set during component initialization.
	// For test utilities, props don't change after mount.
	for (const [key, value] of Object.entries(props.contexts)) {
		setContext(key, value)
	}
</script>

{@render props.children()}

// tests/AddToCart.test.ts
import { render, screen } from '@testing-library/svelte'
import userEvent from '@testing-library/user-event'
import { describe, it, expect, vi } from 'vitest'
import ContextWrapper from './ContextWrapper.svelte'
import AddToCart from '$lib/cart/AddToCart.svelte'
import { createMockCartContext } from './helpers'

test('calls addItem when clicked', async () => {
	const mockCart = createMockCartContext()

	const { getByRole } = render(ContextWrapper, {
		props: {
			contexts: { cart: mockCart }
		}
	})

	await userEvent.click(getByRole('button'))
	expect(mockCart.addItem).toHaveBeenCalled()
})

Práticas de Documentação

Uma boa documentação torna o contexto utilizável por desenvolvedores que não o escreveram — incluindo você no futuro.

Comentários JSDoc

Documente todas as funções e interfaces públicas com exemplos:

/**
 * Authentication context providing user state and auth operations.
 *
 * @example
 * ```

svelte
 * <script>
 *   import { getAuthContext } from '$lib/context/auth.svelte'
 *
 *   const auth = getAuthContext()
 * </script>
 *
 * {#if auth.isAuthenticated}
 *   <p>Welcome, {auth.user.name}!</p>
 * {:else}
 *   <LoginForm />
 * {/if}
 *

/ export interface AuthContext { /* The currently authenticated user, or null if not logged in */ readonly user: User | null

/** Whether a user is currently authenticated */
readonly isAuthenticated: boolean

/** Whether an authentication operation is in progress */
readonly isLoading: boolean

/** The most recent authentication error, if any */
readonly error: string | null

/**
 * Authenticates a user with email and password.
 *
 * @param email - User's email address
 * @param password - User's password
 * @throws {AuthError} If credentials are invalid
 *
 * @example
 * ```

typescript * try { * await auth.login('user@example.com', 'password123') * goto('/dashboard') * } catch (e) { * console.error('Login failed:', e.message) * } *

	 */
	login(email: string, password: string): Promise<void>

	/**
	 * Logs out the current user and clears session data.
	 */
	logout(): Promise<void>
}

README para Diretórios de Contexto

Para aplicações maiores, inclua um README no seu diretório de contexto que documente os contextos disponíveis, seus provedores, consumidores e requisitos de composição. Esse arquivo se torna o ponto de entrada para desenvolvedores que são novos na sua base de código.

Anti-Padrões Comuns

Entender o que não fazer é tão importante quanto conhecer as boas práticas. Esses anti-padrões são armadilhas comuns que desperdiçam tempo de desenvolvimento e criam dores de cabeça na manutenção.

1: Contexto para Cada Prop

Não use contexto apenas para evitar escrever prop={value}. Props são explícitas e autodocumentadas:

<!-- ❌ Over-engineered -->
<!-- Parent.svelte -->
<script>
	import { setContext } from 'svelte'
	setContext('message', 'Hello')
</script>
<Child />

<!-- Child.svelte -->
<script>
	import { getContext } from 'svelte'
	const message = getContext('message')
</script>
<p>{message}</p>

<!-- ✅ Just use props -->
<Child message="Hello" />

2: Contextos Monolíticos Enormes

Não coloque tudo em um único contexto. Divida por funcionalidade/domínio:

// ❌ Everything in one blob
setContext('app', {
	user,
	theme,
	cart,
	notifications,
	settings,
	permissions
})

// ✅ Separate concerns
setContext('auth', authContext)
setContext('theme', themeContext)
setContext('cart', cartContext)

3: Sopa de Provedores Profundamente Aninhados

<!-- ❌ Provider soup -->
<AuthProvider>
	<ThemeProvider>
		<LocaleProvider>
			<CartProvider>
				<NotificationProvider>
					<FeatureFlagProvider>
						<App />
					</FeatureFlagProvider>
				</NotificationProvider>
			</CartProvider>
		</LocaleProvider>
	</ThemeProvider>
</AuthProvider>

Consolide em um único provedor composto:

<!-- ✅ Single provider that sets up everything -->
<AppProvider>
	<App />
</AppProvider>

4: Contexto para Comunicação entre Irmãos

O contexto flui para baixo, não lateralmente. Para comunicação entre componentes irmãos, eleve o estado para o ancestral comum deles.

5: Recriando Objetos de Contexto a Cada Renderização

<script>
	// ❌ New object every time
	setContext('config', {
		apiUrl: '/api',
		timeout: 5000
	})
</script>

<script>
	// ✅ Stable reference
	const config = {
		apiUrl: '/api',
		timeout: 5000
	}
	setContext('config', config)
</script>

6: Contexto para Configuração Estática

<script>
	// ❌ Static data doesn't need context
	setContext('apiUrl', 'https://api.example.com')
	setContext('appName', 'My App')
</script>

Use variáveis de ambiente ou constantes em vez disso:

// ✅ Configuration as constants
// src/lib/config.ts
export const API_URL = import.meta.env.VITE_API_URL
export const APP_NAME = 'My App'

7: Contexto para Estilização

<script>
	// ❌ Styling through context
	setContext('buttonColor', '#3b82f6')
	setContext('buttonRadius', '0.5rem')
</script>

Propriedades customizadas CSS lidam melhor com estilização:

<!-- ✅ CSS for styling -->
<div
	style="
  --button-color: #3b82f6;
  --button-radius: 0.5rem;
"
>
	<Button />
</div>

Quando NÃO Usar Context

Context é poderoso, mas não é universalmente apropriado. Saber quando evitá-lo é tão importante quanto saber quando usá-lo.

Use Props Quando...

Props são a escolha certa para comunicação direta entre pai e filho, quando a API do componente deve ser explícita, ou quando você deseja suporte máximo ao TypeScript:

<!-- Props are clearer for direct relationships -->
<Card title="Welcome" variant="primary">
	<p>Card content</p>
</Card>

<!-- Consumers should see exactly what's needed -->
<DatePicker value={selectedDate} minDate={today} maxDate={nextYear} onchange={handleChange} />

Use Stores Quando...

Stores são melhores quando o estado é verdadeiramente global (singleton), precisa persistir entre desmontagens de componentes, ou quando código fora de componentes precisa de acesso:

// A single toast queue for the entire app
export const toasts = writable<Toast[]>([])

// API client needs auth token - stores work anywhere
import { authStore } from '$lib/stores/auth'

export async function apiRequest(path: string) {
	const { token } = get(authStore)
	return fetch(path, {
		headers: { Authorization: `Bearer ${token}` }
	})
}

Use Funções Load do SvelteKit Quando...

Funções load são a escolha certa quando os dados vêm do servidor, diferentes rotas precisam de dados diferentes, ou quando você precisa de busca de dados segura para SSR:

// +page.server.ts - SvelteKit handles this
export const load: PageServerLoad = async ({ locals }) => {
	const user = await getUser(locals.session)
	return { user }
}

Matriz de Referência Rápida

Necessidade	Solução
Passar dados um nível abaixo	Props
Passar dados por 3+ níveis	Context
Estado interno de biblioteca de componentes	Context
Singleton em toda a aplicação	Store
Dados do servidor por rota	SvelteKit load
Dados que sobrevivem aos componentes	Store
Estado compartilhado com escopo de subárvore	Context
Valores diferentes por subárvore	Context
Acesso por código fora de componentes	Store

Conclusão

Boas práticas não são restrições — são padrões que emergem de resolver os mesmos problemas repetidamente. As convenções neste artigo representam a sabedoria acumulada de construir e manter aplicações onde o context desempenha um papel arquitetural central.

O investimento em convenções de nomenclatura traz retornos toda vez que um desenvolvedor (incluindo você no futuro) consegue adivinhar o nome de uma função corretamente sem precisar buscar no código. O investimento em segurança de tipos traz retornos toda vez que o TypeScript captura um erro em tempo de compilação em vez de em produção. O investimento em testabilidade traz retornos quando você pode refatorar a lógica de context com confiança, sabendo que seus testes irão detectar regressões.

Talvez mais importante, saber quando não usar context previne o erro comum de recorrer a uma ferramenta poderosa quando uma mais simples seria suficiente. Props ainda são a escolha certa para comunicação direta entre pai e filho. Stores ainda são a escolha certa para estado verdadeiramente global. Funções load ainda são a escolha certa para dados do servidor. Context preenche um nicho específico — estado compartilhado com escopo de subárvore — e se destaca quando usado de forma adequada.

Aplique esses padrões de forma consistente, e sua arquitetura baseada em context será uma fundação sobre a qual você poderá construir com confiança, e não uma fonte de confusão e bugs.

Principais Conclusões

Essas práticas transformam o context de um recurso simples em uma ferramenta profissional:

Comece com o framework de decisão — Use props para relacionamentos diretos, context para estado compartilhado com escopo de subárvore, stores para singletons globais e funções load para dados do servidor.
Convenções de nomenclatura importam — Use padrões consistentes para chaves (user-auth), funções (createAuthContext, getAuthContext), arquivos (auth.svelte.ts) e componentes (AuthProvider.svelte).
Mantenha as chaves estáveis — Centralize as chaves e as esconda por trás de funções de acesso para permitir mudanças sem quebrar os consumidores.
Tipar tudo explicitamente — Defina interfaces, use createContext ou wrappers tipados, e nunca dependa de inferência de tipos para APIs públicas.
Projete APIs mínimas e orientadas a ações — Exponha getters (não o estado bruto), forneça ações junto com o estado, inclua estados de carregamento/erro e use tipos de resultado para operações falíveis.
Otimize com cuidado — Aplique throttle em atualizações frequentes, divida contexts grandes, compute valores derivados nos providers e inicialize recursos custosos de forma lazy.
Teste em múltiplos níveis — Extraia a lógica para arquivos .svelte.ts para testes unitários, crie componentes wrapper de teste para testes de integração e simule o context ao testar consumidores.
Evite anti-padrões comuns — Sem context para pai-filho direto, sem contexts monolíticos, sem provider soup, sem context para configuração estática ou estilização.

Aplique essas práticas de forma consistente, e sua arquitetura baseada em context será um prazer de trabalhar — manutenível, testável e escalável.

O Que Vem a Seguir

Aprenda o que pode dar errado e como corrigir em Armadilhas e Depuração de Context, cobrindo erros comuns, técnicas de depuração e armadilhas que pegam até desenvolvedores experientes.

Veja Também

Documentação Oficial

Svelte Context — Guia oficial
Svelte Testing — Padrões de teste
Arquivos .svelte.ts — Runes em TypeScript