De Fazer Funcionar a Manter Sustentável

À medida que as aplicações crescem, o desafio muda de "como faço isso funcionar?" para "como mantenho isso sustentável?" As funcionalidades se acumulam—autenticação, carrinho de compras, notificações, preferências do usuário, busca—cada uma com seu próprio estado, lógica e UI. Sem limites claros, essas funcionalidades se misturam. A lógica de autenticação aparece no carrinho. O estado do carrinho é lido por componentes que não deveriam ter conhecimento sobre ele. As mudanças se propagam de forma imprevisível pela base de código.

O contexto fornece um poderoso padrão arquitetural: trate cada funcionalidade como uma unidade autocontida com um limite claro. O contexto se torna a API pública da funcionalidade—um contrato entre a funcionalidade e o restante da aplicação. Os detalhes de implementação ficam ocultos. As dependências se tornam explícitas. Os testes se tornam simples.

Isso não é apenas organização de código por si mesma. Os limites de funcionalidade resolvem problemas reais: tornam a refatoração segura (altere os internos sem quebrar os consumidores), possibilitam a colaboração em equipe (tenha posse de uma funcionalidade de ponta a ponta) e criam documentação natural (a interface do contexto diz exatamente o que uma funcionalidade faz).

Este artigo ensina você a construir módulos de funcionalidade com contexto: como projetar APIs públicas, o que manter privado, quando substituir stores globais e como compor funcionalidades que dependem umas das outras.

O Espaço do Problema

Vamos examinar o que dá errado sem limites claros de funcionalidade.

O Problema da Funcionalidade Dispersa

Considere uma funcionalidade de carrinho de compras que evoluiu organicamente:

// cart-store.ts - Global store, accessible everywhere
export const cartItems = writable<CartItem[]>([])
export const cartTotal = derived(cartItems, items =>
  items.reduce((sum, item) => sum + item.price * item.quantity, 0)
)

// helpers.ts - Utility functions spread around
export function addToCart(product: Product) {
  cartItems.update(items => [...items, { ...product, quantity: 1 }])
}

// validation.ts - Validation logic elsewhere
export function canAddToCart(product: Product, items: CartItem[]) {
  const existing = items.find(i => i.id === product.id)
  return !existing || existing.quantity < 99
}

// CartButton.svelte - Component with business logic mixed in
<script>
  import { cartItems, cartTotal } from '$lib/stores/cart-store'
  import { addToCart, canAddToCart } from '$lib/helpers'
  import { get } from 'svelte/store'

  export let product

  function handleClick() {
    if (canAddToCart(product, get(cartItems))) {
      addToCart(product)
      // Also need to track analytics...
      analytics.track('add_to_cart', { productId: product.id })
      // And maybe show a notification...
      notifications.show('Added to cart!')
    }
  }
</script>

A funcionalidade do carrinho está espalhada por quatro arquivos sem um limite claro. Qualquer componente pode importar cartItems e alterá-lo diretamente. A lógica de negócio (validação, analytics, notificações) vive em componentes de UI. Quando você precisa mudar como o carrinho funciona—por exemplo, adicionando sincronização com o servidor—você precisa vasculhar toda a base de código.

Problemas que Isso Cria

Sem encapsulamento. Qualquer componente pode importar e alterar cartItems diretamente, contornando a validação:

// Someone on another team, unaware of the 99-item limit
cartItems.update((items) => {
	const item = items.find((i) => i.id === '123')
	if (item) item.quantity = 1000 // Oops
	return items
})

Dificuldade nos testes. Para testar CartButton, você precisa mockar stores globais, importar helpers e configurar todo o estado do carrinho:

// Brittle test with many dependencies
vi.mock('$lib/stores/cart-store')
vi.mock('$lib/helpers')
// Now set up all the mocked state...

Riscos de SSR. Stores no nível de módulo persistem entre requisições no servidor. O carrinho do usuário A pode vazar para a resposta do usuário B:

// This runs once when the module loads, not per-request
export const cartItems = writable([]) // Shared across all SSR requests!

Dependências implícitas. Os componentes dependem silenciosamente do estado global. Movê-los ou refatorá-los pode quebrar coisas de maneiras não óbvias.

O que os Limites de Funcionalidade Fornecem

Uma funcionalidade devidamente encapsulada tem esta aparência:

┌─────────────────────────────────────────────────────────────┐
│  FEATURE: Shopping Cart                                     │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  PRIVATE (Internal Implementation)                    │  │
│  │                                                       │  │
│  │  • Raw $state arrays and objects                      │  │
│  │  • Validation functions                               │  │
│  │  • API call helpers                                   │  │
│  │  • Computed derivations                               │  │
│  │  • Persistence logic                                  │  │
│  │  • Side effects                                       │  │
│  └───────────────────────────────────────────────────────┘  │
│                           │                                  │
│                           ▼                                  │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  PUBLIC (Context API)                                 │  │
│  │                                                       │  │
│  │  • items (readonly)                                   │  │
│  │  • count, total (computed)                            │  │
│  │  • add(), remove(), updateQuantity()                  │  │
│  │  • checkout()                                         │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

O contexto é a única forma de entrar ou sair. Os consumidores não sabem (nem se importam) como o carrinho armazena itens, valida quantidades ou persiste dados. Eles simplesmente chamam cart.add(product).

O Modelo Mental do Svelte 5

Os limites de funcionalidade no Svelte 5 são construídos sobre três princípios fundamentais:

Contexto como Contrato

O objeto de contexto define o que uma funcionalidade expõe. É um contrato: "Aqui está o que você pode ler, aqui está o que você pode fazer." Todo o resto é detalhe de implementação.

// This interface IS the public API
interface CartContext {
	// What you can read
	readonly items: CartItem[]
	readonly count: number
	readonly total: number
	readonly isEmpty: boolean

	// What you can do
	add(product: Product): void
	remove(productId: string): void
	updateQuantity(productId: string, quantity: number): void
	clear(): void
}

A interface serve como documentação. Um desenvolvedor que usa a funcionalidade do carrinho lê isso e sabe exatamente o que está disponível.

Provider como Implementação

O componente provider implementa o contrato. Ele cria estado, define lógica e expõe apenas o que a interface do contexto especifica:

<script lang="ts">
	import { setContext } from 'svelte'
	import type { Snippet } from 'svelte'

	let { children }: { children: Snippet } = $props()

	// Private - not in the context interface
	let items = $state<CartItem[]>([])

	function validateQuantity(quantity: number) {
		return Math.max(1, Math.min(99, quantity))
	}

	// Public - matches the context interface
	const cart: CartContext = {
		get items() {
			return items
		},
		get count() {
			return items.reduce((sum, i) => sum + i.quantity, 0)
		}
		// ... rest of implementation
	}

	setContext('cart', cart)
</script>

{@render children()}

O provider detém toda a complexidade da implementação. Os consumidores veem apenas a API limpa.

Escopo pela Árvore de Componentes

O contexto tem escopo automático para a árvore de componentes. Componentes dentro do provider acessam o carrinho; componentes fora não acessam. Esse escopo é explícito e visível na estrutura do seu layout:

<!-- src/routes/shop/+layout.svelte -->
<CartProvider>
	<!-- Everything here can access the cart -->
	{@render children()}
</CartProvider>

Seções diferentes podem ter implementações diferentes. O site de marketing não precisa de um carrinho. O painel administrativo pode precisar de um tipo diferente de carrinho. O contexto torna isso natural.

Implementação

Vamos construir um módulo de funcionalidade completo passo a passo.

Passo 1: Defina o Contrato

Comece com a interface TypeScript. Isso força você a pensar sobre a API antes da implementação:

// src/lib/features/cart/types.ts

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

export interface CartContext {
	// State (readonly to consumers)
	readonly items: readonly CartItem[]
	readonly count: number
	readonly subtotal: number
	readonly isEmpty: boolean

	// Computed
	readonly formattedTotal: string

	// Actions
	add(product: { id: string; name: string; price: number; image?: string }): void
	remove(productId: string): void
	updateQuantity(productId: string, quantity: number): void
	clear(): void

	// Status
	readonly isLoading: boolean
	readonly error: string | null
}

Observe que items retorna readonly CartItem[]. Isso sinaliza ao TypeScript (e aos desenvolvedores) que os consumidores não devem alterar o array diretamente.

Passo 2: Crie a Chave do Contexto

Use um Symbol para chaves à prova de colisão:

// src/lib/features/cart/context.ts

export const CART_KEY = Symbol('cart')

Symbols garantem que mesmo que outra funcionalidade use a string 'cart', não haverá colisão.

Passo 3: Construa o Provider

O provider implementa tudo:

<!-- src/lib/features/cart/CartProvider.svelte -->
<script lang="ts">
	import { setContext } from 'svelte'
	import { browser } from '$app/environment'
	import { CART_KEY } from './context'
	import type { CartContext, CartItem } from './types'
	import type { Snippet } from 'svelte'

	interface Props {
		children: Snippet
	}

	let { children }: Props = $props()

	// ═══════════════════════════════════════════════════════════
	// PRIVATE STATE
	// ═══════════════════════════════════════════════════════════

	let items = $state<CartItem[]>([])
	let isLoading = $state(false)
	let error = $state<string | null>(null)

	// ═══════════════════════════════════════════════════════════
	// PRIVATE HELPERS
	// ═══════════════════════════════════════════════════════════

	function findItem(id: string): CartItem | undefined {
		return items.find((item) => item.id === id)
	}

	function findItemIndex(id: string): number {
		return items.findIndex((item) => item.id === id)
	}

	function validateQuantity(quantity: number): number {
		return Math.max(1, Math.min(99, quantity))
	}

	// ═══════════════════════════════════════════════════════════
	// PERSISTENCE (Private)
	// ═══════════════════════════════════════════════════════════

	const STORAGE_KEY = 'shopping_cart'

	function saveToStorage() {
		if (browser) {
			try {
				localStorage.setItem(STORAGE_KEY, JSON.stringify(items))
			} catch (e) {
				console.error('Failed to save cart:', e)
			}
		}
	}

	function loadFromStorage() {
		if (browser) {
			try {
				const saved = localStorage.getItem(STORAGE_KEY)
				if (saved) {
					const parsed = JSON.parse(saved)
					if (Array.isArray(parsed)) {
						items = parsed
					}
				}
			} catch (e) {
				console.error('Failed to load cart:', e)
				items = []
			}
		}
	}

	// Initialize from storage
	loadFromStorage()

	// ═══════════════════════════════════════════════════════════
	// PUBLIC API (Context)
	// ═══════════════════════════════════════════════════════════

	const cartContext: CartContext = {
		// Readonly state
		get items() {
			return items
		},

		get count() {
			return items.reduce((sum, item) => sum + item.quantity, 0)
		},

		get subtotal() {
			return items.reduce((sum, item) => sum + item.price * item.quantity, 0)
		},

		get isEmpty() {
			return items.length === 0
		},

		get formattedTotal() {
			const total = items.reduce((sum, item) => sum + item.price * item.quantity, 0)
			return new Intl.NumberFormat('en-US', {
				style: 'currency',
				currency: 'USD'
			}).format(total / 100)
		},

		get isLoading() {
			return isLoading
		},

		get error() {
			return error
		},

		// Actions
		add(product) {
			error = null
			const existing = findItem(product.id)

			if (existing) {
				const newQuantity = validateQuantity(existing.quantity + 1)
				if (newQuantity !== existing.quantity) {
					existing.quantity = newQuantity
					saveToStorage()
				}
			} else {
				items.push({
					id: product.id,
					name: product.name,
					price: product.price,
					image: product.image,
					quantity: 1
				})
				saveToStorage()
			}
		},

		remove(productId) {
			error = null
			const index = findItemIndex(productId)
			if (index !== -1) {
				items.splice(index, 1)
				saveToStorage()
			}
		},

		updateQuantity(productId, quantity) {
			error = null
			const item = findItem(productId)

			if (item) {
				if (quantity <= 0) {
					this.remove(productId)
				} else {
					item.quantity = validateQuantity(quantity)
					saveToStorage()
				}
			}
		},

		clear() {
			error = null
			items = []
			saveToStorage()
		}
	}

	setContext(CART_KEY, cartContext)

	// ═══════════════════════════════════════════════════════════
	// SIDE EFFECTS (Private)
	// ═══════════════════════════════════════════════════════════

	$effect(() => {
		// Update document title with cart count
		if (browser && cartContext.count > 0) {
			const originalTitle = document.title.replace(/^\(\d+\)\s*/, '')
			document.title = `(${cartContext.count}) ${originalTitle}`
		}
	})
</script>

{@render children()}

Passo 4: Crie o Hook do Consumidor

Forneça uma forma tipada de acessar o contexto:

// src/lib/features/cart/useCart.ts

import { getContext, hasContext } from 'svelte'
import { CART_KEY } from './context'
import type { CartContext } from './types'

export function useCart(): CartContext {
	if (!hasContext(CART_KEY)) {
		throw new Error(
			'useCart() must be called from a component inside <CartProvider>. ' +
				'Make sure your component is wrapped with CartProvider in a parent layout.'
		)
	}
	return getContext<CartContext>(CART_KEY)
}

export function useCartOptional(): CartContext | null {
	return hasContext(CART_KEY) ? getContext<CartContext>(CART_KEY) : null
}

A mensagem de erro informa aos desenvolvedores exatamente o que deu errado e como corrigir.

Etapa 5: Exporte a API Pública

Controle o que é acessível publicamente:

// src/lib/features/cart/index.ts

// Provider component
export { default as CartProvider } from './CartProvider.svelte'

// Consumer hook
export { useCart, useCartOptional } from './useCart'

// Types for consumers
export type { CartContext, CartItem } from './types'

// Feature-specific components
export { default as CartDrawer } from './components/CartDrawer.svelte'
export { default as CartIcon } from './components/CartIcon.svelte'
export { default as AddToCartButton } from './components/AddToCartButton.svelte'

// Note: CART_KEY is NOT exported - it's an implementation detail

Observe que CART_KEY não é exportado. Os consumidores não precisam dele; eles usam useCart().

Etapa 6: Use o Recurso

<!-- src/routes/shop/+layout.svelte -->
<script lang="ts">
	import { CartProvider } from '$lib/features/cart'
	import type { Snippet } from 'svelte'

	let { children }: { children: Snippet } = $props()
</script>

<CartProvider>
	{@render children()}
</CartProvider>

<!-- src/routes/shop/products/[id]/+page.svelte -->
<script lang="ts">
	import { useCart, AddToCartButton } from '$lib/features/cart'

	let { data } = $props()

	const cart = useCart()
</script>

<h1>{data.product.name}</h1>
<p>{data.product.description}</p>

<AddToCartButton product={data.product} />

{#if !cart.isEmpty}
	<p>You have {cart.count} items in your cart ({cart.formattedTotal})</p>
{/if}

Substituindo Stores Globais

Uma das aplicações mais valiosas dos limites de funcionalidade é substituir stores globais por contexto com escopo.

O Problema dos Stores Globais

Stores Svelte tradicionais são singletons no nível do módulo:

// stores/user.ts
import { writable } from 'svelte/store'

// This is created once when the module loads
export const user = writable<User | null>(null)

Isso cria vários problemas:

Vazamento de estado no SSR. No servidor, o estado do módulo persiste entre requisições. Os dados do Usuário A podem aparecer na resposta do Usuário B.

Isolamento de testes. Os testes compartilham a mesma instância do store, exigindo uma limpeza cuidadosa entre os testes.

Sem escopo natural. O store existe em todo lugar, inclusive nas partes do aplicativo que não precisam dele.

Alternativa com Contexto

// src/lib/features/auth/AuthProvider.svelte
<script lang="ts">
  import { setContext } from 'svelte'
  import type { Snippet } from 'svelte'

  let { children }: { children: Snippet } = $props()

  // State is created fresh for each provider instance
  let user = $state<User | null>(null)
  let isLoading = $state(true)

  const auth = {
    get user() { return user },
    get isAuthenticated() { return user !== null },
    get isLoading() { return isLoading },

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

    logout() {
      user = null
    }
  }

  setContext('auth', auth)

  // Initialize on mount
  $effect(() => {
    checkSession()
  })

  async function checkSession() {
    try {
      const response = await fetch('/api/auth/me')
      if (response.ok) {
        user = await response.json()
      }
    } finally {
      isLoading = false
    }
  }
</script>

{@render children()}

Benefícios:

Seguro para SSR — Cada requisição obtém uma instância nova do provider
Testável — Forneça contexto simulado nos testes
Com escopo — Auth só existe onde você envolve com AuthProvider

Quando Stores Globais Ainda São Apropriados

Stores globais nem sempre estão errados. Use-os para:

Dados verdadeiramente globais e estáticos:

// App version, feature flags, build-time config
export const appConfig = {
	version: __APP_VERSION__,
	environment: import.meta.env.MODE
}

Singletons que devem ser compartilhados:

// WebSocket connection, analytics instance
export const analytics = new Analytics({ ... })

Comunicação entre árvores:

Quando irmãos em diferentes níveis da árvore precisam compartilhar estado e não há ancestral comum, um store pode ser apropriado. Mas considere se reestruturar a árvore de componentes poderia resolver isso com contexto.

Padrões de Isolamento de Funcionalidades

Implementações Diferentes, Mesma Interface

Diferentes partes do seu aplicativo podem precisar do mesmo conceito implementado de formas diferentes:

src/routes/
├── shop/
│   └── +layout.svelte        # Standard cart
├── marketplace/
│   └── +layout.svelte        # Multi-vendor cart
└── gift-shop/
    └── +layout.svelte        # Gift-enabled cart

Cada seção fornece sua própria implementação de carrinho:

<!-- src/routes/gift-shop/+layout.svelte -->
<script lang="ts">
	import { setContext } from 'svelte'
	import type { Snippet } from 'svelte'

	let { children }: { children: Snippet } = $props()

	// Extended cart item with gift options
	interface GiftCartItem {
		id: string
		name: string
		price: number
		quantity: number
		giftWrap: boolean
		giftMessage: string
		recipientEmail: string | null
	}

	let items = $state<GiftCartItem[]>([])

	const cart = {
		get items() {
			return items
		},
		get count() {
			return items.reduce((sum, i) => sum + i.quantity, 0)
		},

		// Gift-specific add method
		add(product: Product, giftOptions?: GiftOptions) {
			items.push({
				id: product.id,
				name: product.name,
				price: product.price,
				quantity: 1,
				giftWrap: giftOptions?.wrap ?? false,
				giftMessage: giftOptions?.message ?? '',
				recipientEmail: giftOptions?.recipientEmail ?? null
			})
		},

		// Gift-specific method
		updateGiftOptions(productId: string, options: Partial<GiftOptions>) {
			const item = items.find((i) => i.id === productId)
			if (item) {
				if (options.wrap !== undefined) item.giftWrap = options.wrap
				if (options.message !== undefined) item.giftMessage = options.message
				if (options.recipientEmail !== undefined) item.recipientEmail = options.recipientEmail
			}
		},

		remove(productId: string) {
			/* ... */
		},
		clear() {
			/* ... */
		}
	}

	// Same key, different implementation
	setContext('cart', cart)
</script>

{@render children()}

Componentes que usam getContext('cart') obtêm a implementação apropriada com base em sua localização na árvore.

Compondo Funcionalidades Dependentes

As funcionalidades frequentemente dependem umas das outras. As notificações podem precisar de autenticação para saber a quem notificar. O carrinho pode precisar das preferências do usuário para formatação de moeda.

<!-- NotificationProvider.svelte -->
<script lang="ts">
	import { setContext, getContext, hasContext } from 'svelte'
	import type { Snippet } from 'svelte'

	let { children }: { children: Snippet } = $props()

	// Depend on auth feature
	interface AuthContext {
		user: User | null
		isAuthenticated: boolean
	}

	const auth = hasContext('auth') ? getContext<AuthContext>('auth') : null

	let notifications = $state<Notification[]>([])

	const notificationContext = {
		get items() {
			return notifications
		},
		get unreadCount() {
			return notifications.filter((n) => !n.read).length
		},

		async refresh() {
			if (!auth?.isAuthenticated) {
				notifications = []
				return
			}

			const response = await fetch('/api/notifications')
			notifications = await response.json()
		},

		markAsRead(id: string) {
			const notification = notifications.find((n) => n.id === id)
			if (notification) {
				notification.read = true
				// Also sync to server...
			}
		}
	}

	setContext('notifications', notificationContext)

	// React to auth changes
	$effect(() => {
		if (auth?.isAuthenticated) {
			notificationContext.refresh()
		} else {
			notifications = []
		}
	})
</script>

{@render children()}

A Ordem de Aninhamento dos Providers Importa

Quando as funcionalidades dependem umas das outras, a ordem de aninhamento dos providers determina o que está disponível:

<!-- ✅ Correct: Auth is available when Notifications initializes -->
<AuthProvider>
	<NotificationProvider>
		{@render children()}
	</NotificationProvider>
</AuthProvider>

<!-- ❌ Wrong: Notifications can't access auth - it doesn't exist yet -->
<NotificationProvider>
	<AuthProvider>
		{@render children()}
	</AuthProvider>
</NotificationProvider>

Erros Comuns e Anti-Padrões

Vamos analisar algumas armadilhas comuns ao projetar limites de funcionalidade com contexto, junto com explicações e correções.

1: Expondo Estado Bruto

// ❌ Consumers can mutate items directly
const cart = {
	items, // Direct reference to $state array
	add(product) {
		items.push(product)
	}
}

Por que quebra: Os consumidores podem contornar seus métodos e mutar o estado diretamente, quebrando a validação e os efeitos colaterais.

Correção: Retorne por meio de getters:

// ✅ Items are accessed through getter
const cart = {
	get items() {
		return items
	},
	add(product) {
		items.push(product)
	}
}

2: Dependências Circulares

<!-- ❌ Cart depends on Notifications, Notifications depends on Cart -->
<CartProvider>
	<!-- Cart shows notifications when items are added -->
	<NotificationProvider>
		<!-- Notifications need cart context to show "View Cart" -->
		{@render children()}
	</NotificationProvider>
</CartProvider>

Por que quebra: Dependências circulares criam problemas de ordem de inicialização e lógica entrelaçada.

Correção: Extraia a preocupação compartilhada:

<!-- ✅ Both features communicate through events or a mediator -->
<EventBusProvider>
	<CartProvider>
		<NotificationProvider>
			{@render children()}
		</NotificationProvider>
	</CartProvider>
</EventBusProvider>

Ou faça as notificações serem puramente passivas (elas não precisam saber sobre o carrinho):

<!-- Cart provider uses notification context to show messages -->
<NotificationProvider>
	<CartProvider>
		{@render children()}
	</CartProvider>
</NotificationProvider>

3: Vazamento de Detalhes de Implementação

// index.ts
export { CART_KEY } from './context' // ❌ Exposing internal key
export { validateQuantity } from './helpers' // ❌ Exposing internal helper
export { cartItems } from './CartProvider.svelte' // ❌ Exposing raw state

Por que quebra: Os consumidores passam a depender de internos. Quando você refatora, quebra o código deles.

Correção: Exporte apenas a API pública:

// index.ts
export { default as CartProvider } from './CartProvider.svelte'
export { useCart } from './useCart'
export type { CartContext, CartItem } from './types'
// Nothing else!

4: Encapsulamento Excessivo

// ❌ Too many tiny features
<ThemeProvider>
  <FontSizeProvider>
    <ColorSchemeProvider>
      <ReducedMotionProvider>
        <LanguageProvider>
          {@render children()}
        </LanguageProvider>
      </ReducedMotionProvider>
    </ColorSchemeProvider>
  </FontSizeProvider>
</ThemeProvider>

Por que é problemático: Todas essas são preferências relacionadas. Separá-las cria complexidade desnecessária.

Correção: Agrupe estado relacionado em funcionalidades coesas:

// ✅ One provider for user preferences
<PreferencesProvider>
  {@render children()}
</PreferencesProvider>

Considerações de Desempenho e Escalabilidade

Custo de Busca no Context

A busca no context é O(1)—é apenas um acesso a um Map. O custo é negligenciável comparado à renderização. Não evite context por razões de desempenho.

Renderização do Provider

Os próprios providers não re-renderizam quando seu estado interno muda. Apenas os consumidores que leem valores alterados re-renderizam:

<script>
	let items = $state([])
	let theme = $state('light')

	setContext('app', {
		get items() {
			return items
		},
		get theme() {
			return theme
		}
	})
</script>

<!-- This component doesn't re-render when items or theme change -->
<!-- Only children reading those values re-render -->
{@render children()}

Árvores de Funcionalidades Grandes

Para funcionalidades com muitos consumidores (como um tema global), a reatividade granular do Svelte garante que apenas os componentes afetados sejam atualizados:

<!-- Component A only reads theme -->
<script>
  const app = getContext('app')
</script>
<div class="theme-{app.theme}">...</div>

<!-- Component B only reads items -->
<script>
  const app = getContext('app')
</script>
{#each app.items as item}...{/each}

Quando theme muda, o Componente A re-renderiza. O Componente B não—ele só lê items.

Quando NÃO Usar Limites de Funcionalidade

Estado Simples e Local

Não envolva tudo em context:

<!-- ✅ Just use local state -->
<script>
	let email = $state('')
	let password = $state('')
</script>

<!-- ❌ Overkill for local form state -->
<FormProvider>
	<FormField name="email" />
	<FormField name="password" />
</FormProvider>
<input bind:value={email} />
<input bind:value={password} />

Use context quando o estado precisar ser compartilhado entre múltiplos componentes em uma subárvore.

Singletons Verdadeiramente Globais

Algumas coisas realmente são globais:

// These are fine as module-level exports
export const analytics = new AnalyticsClient()
export const logger = new Logger()
export const featureFlags = await loadFeatureFlags()

Se é um singleton que nunca muda com base na posição da árvore de componentes, uma exportação de módulo é mais simples que context.

Abstração Prematura

Não crie limites de funcionalidade antes de precisar deles:

// ❌ Starting with complex architecture for a simple feature
src/lib/features/counter/
├── CounterProvider.svelte
├── context.ts
├── types.ts
├── useCounter.ts
└── index.ts

// ✅ Start simple, extract when complexity grows
<script>
  let count = $state(0)
</script>

Extraia para um módulo de funcionalidade quando a funcionalidade crescer o suficiente para se beneficiar do encapsulamento.

Testando Módulos de Funcionalidade

Os limites de funcionalidade tornam os testes simples:

// cart.test.ts
import { render, screen } from '@testing-library/svelte'
import { setContext } from 'svelte'
import CartSummary from './components/CartSummary.svelte'
import { CART_KEY } from './context'
import type { CartContext } from './types'

function createMockCart(overrides: Partial<CartContext> = {}): CartContext {
	return {
		items: [],
		count: 0,
		subtotal: 0,
		isEmpty: true,
		formattedTotal: '$0.00',
		isLoading: false,
		error: null,
		add: vi.fn(),
		remove: vi.fn(),
		updateQuantity: vi.fn(),
		clear: vi.fn(),
		...overrides
	}
}

describe('CartSummary', () => {
	it('shows empty message when cart is empty', () => {
		render(CartSummary, {
			context: new Map([[CART_KEY, createMockCart()]])
		})

		expect(screen.getByText('Your cart is empty')).toBeInTheDocument()
	})

	it('shows item count and total', () => {
		render(CartSummary, {
			context: new Map([
				[
					CART_KEY,
					createMockCart({
						count: 3,
						isEmpty: false,
						formattedTotal: '$29.99'
					})
				]
			])
		})

		expect(screen.getByText(/3 items/)).toBeInTheDocument()
		expect(screen.getByText('$29.99')).toBeInTheDocument()
	})

	it('calls clear when button clicked', async () => {
		const clear = vi.fn()

		render(CartSummary, {
			context: new Map([
				[
					CART_KEY,
					createMockCart({
						isEmpty: false,
						clear
					})
				]
			])
		})

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

		expect(clear).toHaveBeenCalled()
	})
})

Sem estado global para simular ou redefinir. Basta fornecer o context que o componente espera.

Conclusão

Os limites de funcionalidade transformam a forma como você pensa sobre arquitetura de aplicações. Em vez de um emaranhado de stores globais e utilitários espalhados, você obtém módulos autocontidos com interfaces claras. O provider detém a complexidade; os consumidores enxergam apenas a API limpa.

Esse padrão brilha conforme as aplicações crescem. Quando o carrinho precisa de sincronização com o servidor, você muda o provider—os consumidores não sabem nem se importam. Quando você precisa de um carrinho diferente para a loja de presentes, cria um novo provider—mesma interface, implementação diferente. Quando você testa, fornece context simulado—sem estado global para gerenciar.

O insight fundamental é que context não é apenas sobre passar dados por árvores de componentes. É sobre definir contratos entre partes da sua aplicação. A interface do context diz "é isso que essa funcionalidade faz". O provider diz "é assim que ela faz". Os consumidores dizem "não preciso saber—eu só uso a API".

Comece simples. Extraia funcionalidades quando a complexidade justificar. Deixe os limites emergirem de necessidades reais, não de arquitetura teórica. Quando você extrair, os padrões deste artigo servirão bem: interfaces tipadas como contratos, providers como implementações, hooks para consumo e exportações explícitas para controle.

Principais Conclusões

O context define a API pública. O objeto de context é o contrato entre uma funcionalidade e seus consumidores. Tudo que não está no context é detalhe de implementação.

Os providers detêm a implementação. Estado bruto, validação, persistência, efeitos colaterais—tudo vive dentro do provider. Os consumidores interagem apenas por meio da API do context.

Substitua stores globais por context. O context fornece estado com escopo, seguro para SSR e testável. Use-o em vez de stores no nível do módulo para estado de funcionalidade.

Implementações diferentes, mesma interface. Partes diferentes da sua aplicação podem fornecer implementações diferentes da mesma chave de context. Os componentes obtêm a implementação do ancestral mais próximo.

Funcionalidades dependentes precisam de ordenação. Quando funcionalidades dependem umas das outras, a ordem de aninhamento importa. O provider externo inicializa primeiro.

Exporte apenas a API pública. Controle o que os consumidores podem acessar. Não exporte chaves internas, helpers ou estado bruto.

Teste com context simulado. Os limites de funcionalidade facilitam os testes. Forneça context simulado que corresponda à interface e teste os componentes de forma isolada.

O Que Vem a Seguir

Pronto para se aprofundar? O próximo artigo, Designing Context API's, mostra como criar interfaces de context robustas, ergonômicas e à prova de futuro para suas próprias funcionalidades. Você aprenderá convenções de nomenclatura, padrões de design de API e como equilibrar flexibilidade com encapsulamento—para que seus módulos de context sejam agradáveis de usar e fáceis de manter.

Veja Também

Documentação Oficial

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