Por Que Carrinhos de Compras São Difíceis

Um carrinho de compras estressa o gerenciamento de estado: muitas páginas leem e escrevem nele, os totais precisam ser reativos e a persistência precisa ser confiável. O Context oferece um modelo limpo e escalável, mas somente se você evitar a armadilha ingênua do store global que quebra o isolamento SSR, o escopo multi-tenant e a confiabilidade dos testes.

Neste artigo, você vai construir um carrinho pronto para produção com variantes, totais reativos, persistência, validação de descontos e isolamento com escopo, e depois vai estendê-lo com sincronização de servidor e padrões de performance usando $state, $derived e $effect.

Por Que Context para Carrinhos?

Carrinhos de compras parecem um caso perfeito para estado global. Toda página precisa de acesso, certo? Mas eis o que a experiência ensina: estado de carrinho global cria mais problemas do que resolve.

Considere esses cenários reais:

Plataformas de marketplace: Múltiplos vendedores, cada um com seu próprio fluxo de checkout
E-commerce multi-site: Um app serve várias vitrines
Portais B2B: Diferentes departamentos com orçamentos separados
Lista de desejos vs carrinho: Diferentes "sacolas" com comportamento similar
Renderização no servidor: O isolamento de requisições é obrigatório

O Context oferece estado de carrinho com escopo e isolado que escala para essas complexidades. Vamos construí-lo corretamente.

O Problema com Stores Globais

Antes de mergulhar no context, vamos entender por que o estado global — uma escolha aparentemente natural para algo tão universal quanto um carrinho de compras — cria problemas significativos em aplicações de produção.

Global Store Problems:
═══════════════════════

┌──────────────────────────────────────────────────────────────────┐
│                      Global Cart Store                           │
│                                                                  │
│  Problem 1: SSR State Bleed                                      │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Request A: User adds Widget to cart                       │  │
│  │  Request B: Different user sees Widget in their cart! 💥   │  │
│  │                                                            │  │
│  │  On the server, module-level state persists across         │  │
│  │  requests. Without request isolation, users see each       │  │
│  │  other's data.                                             │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                  │
│  Problem 2: No Isolation                                         │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Marketplace with multiple vendors:                        │  │
│  │  - Storefront A: Electronics                               │  │
│  │  - Storefront B: Groceries                                 │  │
│  │  Same cart? Different carts? Global stores can't scope. 💥 │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                  │
│  Problem 3: Testing Nightmares                                   │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Test 1: Adds item, expects count = 1 ✓                    │  │
│  │  Test 2: Runs next, cart already has item from Test 1 💥   │  │
│  │                                                            │  │
│  │  Tests must manually reset state, creating fragile         │  │
│  │  test suites that break in unexpected ways.                │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

O Context resolve todos os três problemas por meio de seu design fundamental:

Segurança no SSR: Cada requisição ao servidor cria uma árvore de componentes nova com suas próprias instâncias de context. O estado não pode vazar entre requisições porque cada uma recebe um context isolado.

Isolamento com Escopo: O context flui para baixo na árvore de componentes. Diferentes seções do seu app podem ter contextos de carrinho completamente diferentes ao aninhar providers com configurações distintas.

Independência nos Testes: Cada teste pode renderizar sua própria árvore de componentes com seu próprio context de carrinho. Sem estado compartilhado, não há poluição entre testes.

Padrões de Carrinho na Prática

O padrão de carrinho mais comum usado em Marketplace é o carrinho unificado. Por quê? Este é um modelo mental mais simples que simplifica a experiência do usuário e o processamento no backend ao consolidar todos os itens em um único carrinho. É o padrão para a maioria dos sites de e-commerce e plataformas como Shopify, Magento e WooCommerce.

No entanto, para esta demo foi escolhido intencionalmente o exemplo de carrinho por vendedor para demonstrar o isolamento de context com escopo. Nesta demo, o app tem um context de carrinho global, e as rotas de vendedor o substituem com um context específico do vendedor. Providers aninhados substituem os contexts pai, então cada subárvore de vendedor obtém sua própria instância de carrinho enquanto o restante do app mantém o carrinho principal.

flowchart TD
	Global["Global Cart Context"]
	Global --> Routes["/products, /cart"]
	Global --> Marketplace["/marketplace"]

	subgraph MarketplaceScope["Vendor Routes"]
		VendorA["Vendor A Context (overrides)"]
		VendorB["Vendor B Context (overrides)"]
		VendorA --> A1[Item 1]
		VendorA --> A2[Item 2]
		VendorB --> B1[Item 1]
		VendorB --> B2[Item 2]
	end

	Marketplace --> VendorA
	Marketplace --> VendorB

Você pode ver esse padrão em ação em plataformas como DoorDash, Uber Eats e Instacart, onde cada restaurante ou loja tem seu próprio carrinho e fluxo de checkout, requisitos de pedido mínimo, processamento de pagamento etc.

Quando faz sentido:

Delivery de comida: Você não pode pedir do McDonald's e do Burger King em uma única entrega
Fulfillment diferente: Cada vendedor envia separadamente com logística incompatível
Processadores de pagamento diferentes: Cada vendedor gerencia seus próprios pagamentos
Atacado B2B: Diferentes termos, contratos, pedidos mínimos por fornecedor
Vitrines white-label: Cada vendedor é essencialmente sua própria loja com marca própria

Visão Geral da Arquitetura do Carrinho

Um sistema de carrinho bem arquitetado separa responsabilidades de forma limpa. Veja como as peças se encaixam:

Cart System Architecture:
═════════════════════════

┌──────────────────────────────────────────────────────────────────┐
│                          App Root                                │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │                     CartProvider                           │  │
│  │  ┌──────────────────────────────────────────────────────┐  │  │
│  │  │  Reactive State ($state)                             │  │  │
│  │  │  ├── items: CartItem[]                               │  │  │
│  │  │  ├── appliedDiscount: AppliedDiscount | null         │  │  │
│  │  │  └── isLoading: boolean                              │  │  │
│  │  └──────────────────────────────────────────────────────┘  │  │
│  │                           │                                │  │
│  │                           ▼                                │  │
│  │  ┌──────────────────────────────────────────────────────┐  │  │
│  │  │  Derived Calculations ($derived)                     │  │  │
│  │  │  ├── itemCount, totalQuantity                        │  │  │
│  │  │  ├── subtotal, discountAmount                        │  │  │
│  │  │  ├── shipping, tax                                   │  │  │
│  │  │  └── total, isEmpty, summary                         │  │  │
│  │  └──────────────────────────────────────────────────────┘  │  │
│  │                           │                                │  │
│  │                           ▼                                │  │
│  │  ┌──────────────────────────────────────────────────────┐  │  │
│  │  │  Side Effects ($effect)                              │  │  │
│  │  │  └── Persistence to localStorage                     │  │  │
│  │  └──────────────────────────────────────────────────────┘  │  │
│  │                                                            │  │
│  │  Context API (actions):                                    │  │
│  │  ├── addItem(product, quantity, options)                   │  │
│  │  ├── updateQuantity(itemId, quantity)                      │  │
│  │  ├── removeItem(itemId)                                    │  │
│  │  ├── applyDiscount(code) → Promise<Result>                 │  │
│  │  ├── removeDiscount()                                      │  │
│  │  └── clearCart()                                           │  │
│  │                                                            │  │
│  │  ┌──────────────────────────────────────────────────────┐  │  │
│  │  │                   Consumer Components                │  │  │
│  │  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │  │  │
│  │  │  │ ProductPage │  │  CartIcon   │  │  Checkout   │   │  │  │
│  │  │  │ addItem()   │  │ itemCount   │  │ totals      │   │  │  │
│  │  │  └─────────────┘  └─────────────┘  └─────────────┘   │  │  │
│  │  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │  │  │
│  │  │  │  MiniCart   │  │ CartDrawer  │  │CartSummary  │   │  │  │
│  │  │  │ items, qty  │  │ full cart   │  │ breakdown   │   │  │  │
│  │  │  └─────────────┘  └─────────────┘  └─────────────┘   │  │  │
│  │  └──────────────────────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

A arquitetura segue um fluxo de dados claro: $state mantém a fonte da verdade, $derived computa todos os valores secundários, $effect lida com efeitos colaterais como persistência, e a API de context expõe tanto o estado quanto as ações para os componentes consumidores.

Planejando o Sistema de Carrinho

Antes de escrever código, vamos definir o que um carrinho de compras de produção precisa lidar. Pensar nos requisitos antecipadamente leva a um design de API melhor.

Requisitos Básicos

Categoria	Operações	Descrição
Gerenciamento de Itens	Adicionar, atualizar, remover	Lidar com produtos com variantes (tamanho, cor)
Controle de Quantidade	Incrementar, decrementar, definir	Respeitar limites de estoque, validar intervalos
Cálculos	Subtotal, imposto, frete, total	Recálculo reativo e automático
Descontos	Aplicar, validar, remover	Códigos promocionais validados no servidor
Persistência	Salvar, carregar, sincronizar	Sobreviver a atualizações de página, opcionalmente sincronizar com o servidor
Consultas	Verificar conteúdo, obter quantidades	Buscas eficientes para estado da UI

Decisões de Modelagem de Dados

Algumas decisões afetam como modelamos os dados do carrinho:

Identidade do Item: Apenas o ID do produto não é suficiente quando um mesmo produto tem variantes. Uma camiseta azul no tamanho G é uma linha de carrinho diferente da mesma camiseta no tamanho M. Geramos identificadores compostos a partir do ID do produto mais as opções de variante.

Armazenamento de Preços: Armazenar preços em centavos como inteiros evita problemas de precisão de ponto flutuante. Um preço de $19.99 vira 1999 centavos. Todos os cálculos usam inteiros, e formatamos para moeda apenas na exibição.

Limites de Estoque: O carrinho aplica limites de maxQuantity. Adicionar itens além do estoque disponível falha de forma elegante com um resultado de erro tipado.

Cálculos: Todos os valores derivados — subtotais, impostos, frete — são computados via $derived. Cada componente vê valores consistentes e automaticamente sincronizados.

Objetos de Resultado: Operações do carrinho retornam objetos de resultado tipados em vez de lançar erros. Isso torna o tratamento de erros explícito e type-safe.

O Que Você Vai Construir

Neste tutorial, você vai construir uma aplicação de carrinho de compras completa usando a API de Context e runes do Svelte 5. O projeto abrange gerenciamento de estado reativo, persistência com localStorage, isolamento de carrinho multi-vendedor, um sistema de lista de desejos e códigos de desconto validados no servidor — tudo isso sem nenhuma biblioteca externa de gerenciamento de estado.

Um carrinho de compras com operações de adicionar/remover/atualizar, limites de quantidade e totais por linha
Um sistema de lista de desejos que funciona junto com o carrinho
Um marketplace multi-vendedor onde cada vendedor tem um carrinho isolado com sua própria moeda, alíquota de imposto e regras de frete
Um sistema de código de desconto com validação no lado do servidor
Estado persistente usando localStorage com salvamento/carregamento automático via $effect
Componentes de UI reutilizáveis com snippets do Svelte 5 e $props()

Pré-requisitos

Node.js 18+
Conhecimento básico de Svelte e TypeScript
Familiaridade com roteamento no SvelteKit

1. Configuração do Projeto

Crie um novo projeto SvelteKit e instale as dependências:

npx sv create sv-cart
cd sv-cart
pnpm install lucide-svelte

Escolha o template TypeScript quando solicitado. Seu package.json deve incluir:

{
	"devDependencies": {
		"@sveltejs/adapter-node": "^5.5.2",
		"@sveltejs/kit": "^2.50.2",
		"svelte": "^5.49.2",
		"typescript": "^5.9.3",
		"vite": "^7.3.1"
	},
	"dependencies": {
		"lucide-svelte": "^0.564.0"
	}
}

Estrutura do Projeto

Esta é a estrutura de arquivos que vamos construir:

src/
├── lib/
│   ├── cart/
│   │   ├── types.ts                  # Cart type definitions
│   │   ├── cart-context.svelte.ts     # Cart state + context
│   │   ├── CartProvider.svelte        # Provider component
│   │   ├── AddToCartButton.svelte     # Add-to-cart with feedback
│   │   ├── CartIcon.svelte            # Header badge icon
│   │   ├── CartSummary.svelte         # Order summary + discounts
│   │   ├── QuantitySelector.svelte    # +/- quantity control
│   │   └── vendor-carts.svelte.ts     # Cross-vendor summary
│   ├── wishlist/
│   │   ├── types.ts                   # Wishlist types
│   │   ├── wishlist-context.svelte.ts # Wishlist state + context
│   │   ├── WishlistProvider.svelte    # Provider component
│   │   ├── WishlistButton.svelte      # Toggle heart button
│   │   └── WishlistIcon.svelte        # Header badge icon
│   ├── components/
│   │   ├── Header.svelte              # Site header
│   │   ├── ProductCard.svelte         # Reusable product card
│   │   ├── VendorHeader.svelte        # Vendor navigation
│   │   └── VendorLogo.svelte          # Dynamic icon renderer
│   ├── config/
│   │   └── routes.ts                  # Route constants
│   ├── data/
│   │   └── products.ts               # Product & vendor data
│   └── utils/
│       └── formatting.ts             # Price formatting
├── routes/
│   ├── +layout.svelte                # Root layout
│   ├── api/coupons/validate/
│   │   └── +server.ts                # Discount validation API
│   └── demo/
│       ├── +layout@.svelte           # Demo layout with Header
│       ├── +page.svelte              # Demo home
│       ├── products/+page.svelte     # All products
│       ├── cart/+page.svelte         # Cart page
│       ├── wishlist/+page.svelte     # Wishlist page
│       ├── marketplace/+page.svelte  # Vendor directory
│       └── (vendor)/                 # Vendor group
│           ├── +layout@.svelte
│           └── marketplace/[vendor]/
│               ├── +layout.server.ts
│               ├── +layout.svelte
│               ├── +page.svelte
│               ├── cart/+page.svelte
│               └── wishlist/+page.svelte
└── app.css                           # Global styles

2. Definir os Tipos

Comece definindo as interfaces TypeScript que descrevem o modelo de dados do seu carrinho. Todo valor monetário é armazenado em centavos para evitar problemas de ponto flutuante.

Crie src/lib/cart/types.ts:

// src/lib/cart/types.ts

/**
 * Product information required for cart operations.
 * This is the minimum data needed to add an item.
 */
export interface CartProduct {
	/** Unique product identifier from your catalog */
	id: string

	/** Display name for the product */
	name: string

	/** Price per unit in cents (e.g., 1999 = $19.99) */
	price: number

	/** URL to product image for display in cart */
	image?: string

	/** SKU for inventory tracking */
	sku?: string

	/** Maximum allowed quantity (stock limit) */
	maxQuantity?: number
}

/**
 * Options/variants for a cart item.
 * Supports arbitrary key-value pairs for flexibility.
 */
export interface CartItemOptions {
	size?: string
	color?: string
	[key: string]: string | undefined
}

/**
 * A single item in the shopping cart.
 * Each item tracks a specific product variant and quantity.
 */
export interface CartItem {
	/** Unique identifier for this cart entry (product + options) */
	id: string

	/** Reference to the original product data */
	product: CartProduct

	/** How many of this item the user wants */
	quantity: number

	/** Selected options/variants for this item */
	options: CartItemOptions

	/** When this item was added to the cart */
	addedAt: Date

	/** Computed: price x quantity for this line */
	lineTotal: number
}

/**
 * Applied discount/coupon information.
 */
export interface AppliedDiscount {
	/** The discount code used */
	code: string

	/** Type of discount calculation */
	type: 'percentage' | 'fixed'

	/** The discount value (percentage or cents) */
	value: number

	/** The actual amount discounted in cents */
	appliedAmount: number
}

/**
 * Calculated summary of the cart's current state.
 * All monetary values are in cents.
 */
export interface CartSummary {
	/** Number of unique items (different products/variants) */
	itemCount: number

	/** Total number of units across all items */
	totalQuantity: number

	/** Sum of (price x quantity) for all items */
	subtotal: number

	/** Discount amount if a code is applied */
	discount: number

	/** Calculated tax amount */
	tax: number

	/** Shipping cost (may be zero for free shipping) */
	shipping: number

	/** Final total: subtotal - discount + tax + shipping */
	total: number
}

/**
 * Result of attempting to add an item to the cart.
 * Operations return result objects rather than throwing errors.
 */
export interface AddItemResult {
	success: boolean
	error?: 'MAX_QUANTITY_EXCEEDED' | 'INVALID_QUANTITY' | 'INVALID_PRODUCT'
	item?: CartItem
	message?: string
}

/**
 * Result of attempting to update an item's quantity.
 */
export interface UpdateQuantityResult {
	success: boolean
	error?: 'ITEM_NOT_FOUND' | 'MAX_QUANTITY_EXCEEDED' | 'INVALID_QUANTITY'
	message?: string
}

/**
 * Result of attempting to apply a discount code.
 */
export interface DiscountResult {
	success: boolean
	discount?: AppliedDiscount
	error?: string
}

/**
 * Configuration options for the cart provider.
 */
export interface CartOptions {
	/** Storage key for persistence (default: 'cart') */
	storageKey?: string

	/** Currency code (default: 'USD') */
	currency?: string

	/** Tax rate as a decimal (default: 0.08 for 8%) */
	taxRate?: number

	/** Subtotal threshold for free shipping in cents (default: 5000) */
	freeShippingThreshold?: number

	/** Standard shipping cost in cents (default: 599) */
	shippingCost?: number

	/** Custom shipping calculation function */
	calculateShipping?: (subtotal: number, itemCount: number) => number

	/** API endpoint for coupon validation */
	couponEndpoint?: string
}

/**
 * The public API of the cart context.
 * This interface documents everything components can do with the cart.
 */
export interface CartContext {
	// Reactive state (readonly to consumers)
	readonly items: CartItem[]
	readonly summary: CartSummary
	readonly isEmpty: boolean
	readonly isLoading: boolean
	readonly appliedDiscount: AppliedDiscount | null
	readonly currency: string

	// Convenience accessors
	readonly itemCount: number
	readonly totalQuantity: number

	// Item operations
	addItem(product: CartProduct, quantity?: number, options?: CartItemOptions): AddItemResult
	updateQuantity(id: string, quantity: number): UpdateQuantityResult
	removeItem(id: string): void
	clearCart(): void

	// Queries
	getItem(productId: string, options?: CartItemOptions): CartItem | undefined
	hasItem(productId: string, options?: CartItemOptions): boolean
	getQuantity(productId: string, options?: CartItemOptions): number

	// Discounts
	applyDiscount(code: string): Promise<DiscountResult>
	removeDiscount(): void
}

Por Que Objetos de Resultado em Vez de Exceções?

Note que addItem retorna AddItemResult em vez de lançar um erro. Esse padrão dá aos chamadores controle explícito sobre o tratamento de erros sem try/catch, e torna os possíveis modos de falha visíveis no sistema de tipos.

3. Criar o Context do Carrinho

Este é o núcleo da aplicação. O context do carrinho usa runes do Svelte 5 ($state, $derived, $effect) para estado reativo, e a API de Context (setContext/getContext) para disponibilizá-lo em toda a árvore de componentes.

Crie src/lib/cart/cart-context.svelte.ts:

// src/lib/cart/cart-context.svelte.ts

import { browser } from '$app/environment'
import { getContext, hasContext, setContext } from 'svelte'
import { SvelteDate } from 'svelte/reactivity'
import type {
	AddItemResult,
	AppliedDiscount,
	CartContext,
	CartItem,
	CartItemOptions,
	CartOptions,
	CartProduct,
	CartSummary,
	DiscountResult,
	UpdateQuantityResult
} from './types'

/**
 * Symbol key ensures no collisions with other contexts.
 */
const CART_KEY = Symbol('cart')

/**
 * Creates and provides the cart context.
 * Call this in your root layout or a dedicated CartProvider component.
 */
export function createCartContext(options: CartOptions = {}): CartContext {
	const {
		storageKey = 'cart',
		currency = 'USD',
		taxRate = 0.08,
		freeShippingThreshold = 5000,
		shippingCost = 599,
		calculateShipping,
		couponEndpoint = '/api/coupons/validate'
	} = options

	// ─── State Initialization ────────────────────────────────

	let items = $state<CartItem[]>([])
	let appliedDiscount = $state<AppliedDiscount | null>(null)
	let isLoading = $state(false)
	let isInitialized = $state(false)

	// ─── Persistence - Load on Mount ─────────────────────────

	function loadFromStorage(): void {
		if (!browser) return

		try {
			const stored = localStorage.getItem(storageKey)
			if (!stored) {
				isInitialized = true
				return
			}

			const data = JSON.parse(stored)

			if (!data || !Array.isArray(data.items)) {
				isInitialized = true
				return
			}

			// Restore items with proper Date objects
			items = data.items.map((item: CartItem) => ({
				...item,
				addedAt: new SvelteDate(item.addedAt)
			}))

			if (data.discount) {
				appliedDiscount = data.discount
			}

			isInitialized = true
		} catch (error) {
			console.warn('Failed to load cart from storage:', error)
			isInitialized = true
		}
	}

	// Load on mount (client-side only)
	$effect.pre(() => {
		if (!browser || isInitialized) return
		loadFromStorage()
	})

	// ─── Derived Calculations ────────────────────────────────

	const itemCount = $derived(items.length)

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

	const subtotal = $derived(items.reduce((sum, item) => sum + item.lineTotal, 0))

	const discountAmount = $derived.by(() => {
		if (!appliedDiscount) return 0

		if (appliedDiscount.type === 'fixed') {
			return Math.min(appliedDiscount.value, subtotal)
		}

		// Percentage discount
		return Math.round(subtotal * (appliedDiscount.value / 100))
	})

	const afterDiscount = $derived(Math.max(0, subtotal - discountAmount))

	const shipping = $derived.by(() => {
		if (calculateShipping) {
			return calculateShipping(afterDiscount, itemCount)
		}
		return afterDiscount >= freeShippingThreshold ? 0 : shippingCost
	})

	const tax = $derived(Math.round(afterDiscount * taxRate))

	const total = $derived(afterDiscount + shipping + tax)

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

	const summary = $derived<CartSummary>({
		itemCount,
		totalQuantity,
		subtotal,
		discount: discountAmount,
		tax,
		shipping,
		total
	})

	// ─── Persistence Effect ──────────────────────────────────

	$effect(() => {
		if (!browser || !isInitialized) return

		const data = {
			items,
			discount: appliedDiscount,
			updatedAt: Date.now()
		}

		try {
			localStorage.setItem(storageKey, JSON.stringify(data))
		} catch (error) {
			console.warn('Failed to save cart to storage:', error)
		}
	})

	// ─── Helper Functions ────────────────────────────────────

	function generateItemId(productId: string, options: CartItemOptions): string {
		const optionsKey = Object.entries(options)
			.filter(([_, v]) => v !== undefined)
			.sort(([a], [b]) => a.localeCompare(b))
			.map(([k, v]) => `${k}:${v}`)
			.join('|')

		return optionsKey ? `${productId}__${optionsKey}` : productId
	}

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

	function findItemByProduct(
		productId: string,
		options: CartItemOptions = {}
	): CartItem | undefined {
		const targetId = generateItemId(productId, options)
		return items.find((item) => item.id === targetId)
	}

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

	// ─── Context Object ──────────────────────────────────────

	const context: CartContext = {
		get items() {
			return items
		},
		get summary() {
			return summary
		},
		get isEmpty() {
			return isEmpty
		},
		get isLoading() {
			return isLoading
		},
		get appliedDiscount() {
			return appliedDiscount
		},
		get currency() {
			return currency
		},
		get itemCount() {
			return itemCount
		},
		get totalQuantity() {
			return totalQuantity
		},

		addItem(product: CartProduct, quantity = 1, options: CartItemOptions = {}): AddItemResult {
			// Validate product
			if (!product?.id || !product?.name || typeof product.price !== 'number') {
				return {
					success: false,
					error: 'INVALID_PRODUCT',
					message: 'Product must have id, name, and price'
				}
			}

			// Validate quantity
			if (quantity < 1 || !Number.isInteger(quantity)) {
				return {
					success: false,
					error: 'INVALID_QUANTITY',
					message: 'Quantity must be a positive integer'
				}
			}

			const itemId = generateItemId(product.id, options)
			const existing = findItemById(itemId)

			if (existing) {
				const newQuantity = existing.quantity + quantity
				const maxQty = product.maxQuantity ?? Infinity

				if (newQuantity > maxQty) {
					return {
						success: false,
						error: 'MAX_QUANTITY_EXCEEDED',
						message: `Maximum ${maxQty} allowed`
					}
				}

				existing.quantity = newQuantity
				existing.lineTotal = newQuantity * existing.product.price
				return { success: true, item: existing }
			}

			// Check stock limit for new items
			if (product.maxQuantity && quantity > product.maxQuantity) {
				return {
					success: false,
					error: 'MAX_QUANTITY_EXCEEDED',
					message: `Maximum ${product.maxQuantity} allowed`
				}
			}

			const newItem: CartItem = {
				id: itemId,
				product,
				quantity,
				options,
				addedAt: new SvelteDate(),
				lineTotal: quantity * product.price
			}

			items.push(newItem)
			return { success: true, item: newItem }
		},

		updateQuantity(id: string, quantity: number): UpdateQuantityResult {
			if (!Number.isInteger(quantity)) {
				return {
					success: false,
					error: 'INVALID_QUANTITY',
					message: 'Quantity must be an integer'
				}
			}

			const item = findItemById(id)

			if (!item) {
				return {
					success: false,
					error: 'ITEM_NOT_FOUND',
					message: 'Item not found in cart'
				}
			}

			if (quantity <= 0) {
				this.removeItem(id)
				return { success: true }
			}

			const maxQty = item.product.maxQuantity ?? Infinity
			if (quantity > maxQty) {
				return {
					success: false,
					error: 'MAX_QUANTITY_EXCEEDED',
					message: `Maximum ${maxQty} allowed`
				}
			}

			item.quantity = quantity
			item.lineTotal = quantity * item.product.price
			return { success: true }
		},

		removeItem(id: string): void {
			const index = findItemIndex(id)
			if (index !== -1) {
				items.splice(index, 1)
			}
		},

		clearCart(): void {
			items.length = 0
			appliedDiscount = null
		},

		getItem(productId: string, options: CartItemOptions = {}): CartItem | undefined {
			return findItemByProduct(productId, options)
		},

		hasItem(productId: string, options: CartItemOptions = {}): boolean {
			return findItemByProduct(productId, options) !== undefined
		},

		getQuantity(productId: string, options: CartItemOptions = {}): number {
			const item = findItemByProduct(productId, options)
			return item?.quantity ?? 0
		},

		async applyDiscount(code: string): Promise<DiscountResult> {
			if (!code.trim()) {
				return {
					success: false,
					error: 'Please enter a discount code'
				}
			}

			isLoading = true

			try {
				const response = await fetch(couponEndpoint, {
					method: 'POST',
					headers: { 'Content-Type': 'application/json' },
					body: JSON.stringify({
						code: code.trim().toUpperCase(),
						subtotal
					})
				})

				const data = await response.json()

				if (!response.ok) {
					return {
						success: false,
						error: data.message ?? 'Invalid discount code'
					}
				}

				appliedDiscount = {
					code: data.code,
					value: data.value,
					type: data.type,
					appliedAmount: data.appliedAmount
				}

				return { success: true, discount: appliedDiscount }
			} catch (error) {
				console.error('Discount validation error:', error)
				return {
					success: false,
					error: 'Unable to validate discount code. Please try again.'
				}
			} finally {
				isLoading = false
			}
		},

		removeDiscount(): void {
			appliedDiscount = null
		}
	}

	return setContext(CART_KEY, context)
}

/**
 * Retrieves the cart context.
 * Must be called from a component inside a CartProvider.
 */
export function getCartContext(): CartContext {
	if (!hasContext(CART_KEY)) {
		throw new Error(
			'Cart context not found. ' +
				'Ensure your component is inside a CartProvider or the root layout.'
		)
	}
	return getContext(CART_KEY)
}

/**
 * Checks if cart context is available.
 */
export function hasCartContext(): boolean {
	return hasContext(CART_KEY)
}

Principais Decisões de Design

Symbol('cart') como chave de context evita colisões se outras bibliotecas também usarem context.
Propriedades getter no objeto de context (get items()) garantem que os consumidores sempre leiam o valor reativo mais recente.
$effect.pre carrega os dados persistidos antes da primeira renderização para evitar um flash de conteúdo vazio.
$effect para salvamento automático é executado sempre que items ou appliedDiscount mudam — sem necessidade de chamadas manuais de salvamento.
SvelteDate é usado em vez de Date porque o sistema de reatividade do Svelte 5 consegue rastrear alterações em instâncias de SvelteDate.
generateItemId cria um ID determinístico a partir do ID do produto + opções ordenadas, para que o mesmo produto com variantes diferentes (ex.: size:M vs size:L) receba entradas separadas no carrinho.

4. Construir o Componente CartProvider

O CartProvider é um wrapper fino que chama createCartContext e renderiza seus filhos. Usar untrack garante que o context seja criado apenas uma vez com os valores iniciais das props.

Crie src/lib/cart/CartProvider.svelte:

<!-- src/lib/cart/CartProvider.svelte -->
<script lang="ts">
	import type { Snippet } from 'svelte'
	import { untrack } from 'svelte'
	import { createCartContext } from './cart-context.svelte'
	import type { CartOptions } from './types'

	interface Props extends CartOptions {
		children: Snippet
	}

	let {
		storageKey,
		currency,
		taxRate,
		freeShippingThreshold,
		shippingCost,
		calculateShipping,
		couponEndpoint,
		children
	}: Props = $props()

	// Create context once with initial values
	untrack(() => {
		createCartContext({
			storageKey,
			currency,
			taxRate,
			freeShippingThreshold,
			shippingCost,
			calculateShipping,
			couponEndpoint
		})
	})
</script>

{@render children()}

Por Que `untrack`?

Sem untrack, o sistema de reatividade do Svelte rastrearia as props dentro do callback. Se um pai re-renderizasse e passasse novos valores de props, isso poderia acionar a criação do context novamente. untrack captura os valores iniciais e ignora mudanças subsequentes — o context é criado exatamente uma vez.

5. Criar o Context da Lista de Desejos

A lista de desejos é mais simples do que o carrinho — ela apenas rastreia produtos sem quantidades. Segue o mesmo padrão da API de Context.

Crie src/lib/wishlist/types.ts:

// src/lib/wishlist/types.ts

import type { CartProduct } from '$lib/cart/types'

export interface WishlistItem {
	product: CartProduct
	addedAt: Date
}

export interface WishlistContext {
	readonly items: WishlistItem[]
	readonly count: number
	readonly isEmpty: boolean

	add(product: CartProduct): void
	remove(productId: string): void
	has(productId: string): boolean
	clear(): void
	toggle(product: CartProduct): void
}

Crie src/lib/wishlist/wishlist-context.svelte.ts:

// src/lib/wishlist/wishlist-context.svelte.ts

import { browser } from '$app/environment'
import type { CartProduct } from '$lib/cart/types'
import { getContext, hasContext, setContext } from 'svelte'
import { SvelteDate } from 'svelte/reactivity'
import type { WishlistContext, WishlistItem } from './types'

const WISHLIST_KEY = Symbol('wishlist')

export function createWishlistContext(storageKey = 'wishlist'): WishlistContext {
	let items = $state<WishlistItem[]>([])
	let isInitialized = $state(false)

	function loadFromStorage(): void {
		if (!browser) return

		try {
			const stored = localStorage.getItem(storageKey)
			if (stored) {
				const data = JSON.parse(stored)
				items = data.map((item: WishlistItem) => ({
					...item,
					addedAt: new SvelteDate(item.addedAt)
				}))
			}
			isInitialized = true
		} catch (error) {
			console.warn('Failed to load wishlist:', error)
			isInitialized = true
		}
	}

	$effect.pre(() => {
		if (!browser || isInitialized) return
		loadFromStorage()
	})

	const count = $derived(items.length)
	const isEmpty = $derived(items.length === 0)

	$effect(() => {
		if (!browser || !isInitialized) return
		localStorage.setItem(storageKey, JSON.stringify(items))
	})

	const context: WishlistContext = {
		get items() {
			return items
		},
		get count() {
			return count
		},
		get isEmpty() {
			return isEmpty
		},

		add(product: CartProduct): void {
			if (!items.some((i) => i.product.id === product.id)) {
				items.push({ product, addedAt: new SvelteDate() })
			}
		},

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

		has(productId: string): boolean {
			return items.some((i) => i.product.id === productId)
		},

		toggle(product: CartProduct): void {
			if (this.has(product.id)) {
				this.remove(product.id)
			} else {
				this.add(product)
			}
		},

		clear(): void {
			items.length = 0
		}
	}

	return setContext(WISHLIST_KEY, context)
}

export function getWishlistContext(): WishlistContext {
	if (!hasContext(WISHLIST_KEY)) {
		throw new Error('Wishlist context not found.')
	}
	return getContext(WISHLIST_KEY)
}

6. Construa o Componente WishlistProvider

Crie src/lib/wishlist/WishlistProvider.svelte:

<!-- src/lib/wishlist/WishlistProvider.svelte -->
<script lang="ts">
	import type { Snippet } from 'svelte'
	import { untrack } from 'svelte'
	import { createWishlistContext } from './wishlist-context.svelte'

	interface Props {
		storageKey?: string
		children: Snippet
	}

	let { storageKey = 'wishlist', children }: Props = $props()

	untrack(() => {
		createWishlistContext(storageKey)
	})
</script>

{@render children()}

7. Dados de Produtos e Utilitários

Constantes de Rotas

Crie src/lib/config/routes.ts:

// src/lib/config/routes.ts

export const ROUTES = {
	HOME: '/',
	DEMO: '/demo',
	PRODUCTS: '/demo/products',
	MARKETPLACE: '/demo/marketplace',
	CART: '/demo/cart',
	WISHLIST: '/demo/wishlist',

	vendor: (slug: string) => `/demo/marketplace/${slug}`,
	vendorCart: (slug: string) => `/demo/marketplace/${slug}/cart`,
	vendorWishlist: (slug: string) => `/demo/marketplace/${slug}/wishlist`,

	apiValidateCoupon: '/api/coupons/validate'
} as const

Formatação de Preços

Crie src/lib/utils/formatting.ts:

// src/lib/utils/formatting.ts

export function formatPrice(cents: number, currency = 'USD'): string {
	return new Intl.NumberFormat('en-US', {
		style: 'currency',
		currency
	}).format(cents / 100)
}

Dados de Produtos e Fornecedores

Crie src/lib/data/products.ts:

// src/lib/data/products.ts

export interface Vendor {
	id: string
	name: string
	slug: string
	description: string
	logo?: string
	location?: string
	currency: string
	taxRate: number
	shippingCost: number
}

export interface Product {
	id: string
	vendorId: string
	name: string
	description: string
	price: number // in cents
	image: string
	category: string
	sku: string
	maxQuantity: number
	inStock: boolean
	tags: string[]
}

export const vendors: Vendor[] = [
	{
		id: 'vendor-1',
		name: 'TechGear Pro',
		slug: 'techgear-pro',
		description: 'Premium electronics and gadgets for tech enthusiasts',
		logo: 'headphones',
		location: 'San Francisco, CA',
		currency: 'USD',
		taxRate: 0.0875,
		shippingCost: 799
	},
	{
		id: 'vendor-2',
		name: 'Artisan Crafts Co',
		slug: 'artisan-crafts',
		description: 'Handmade artisanal products with care and quality',
		logo: 'palette',
		location: 'Portland, OR',
		currency: 'USD',
		taxRate: 0.08,
		shippingCost: 599
	},
	{
		id: 'vendor-3',
		name: 'FitLife Essentials',
		slug: 'fitlife-essentials',
		description: 'Health, fitness, and wellness products for active lifestyles',
		logo: 'zap',
		location: 'Austin, TX',
		currency: 'USD',
		taxRate: 0.0825,
		shippingCost: 499
	},
	{
		id: 'vendor-4',
		name: 'HomeStyle Living',
		slug: 'homestyle-living',
		description: 'Modern home decor and lifestyle accessories',
		logo: 'home',
		location: 'Seattle, WA',
		currency: 'USD',
		taxRate: 0.101,
		shippingCost: 699
	}
]

export const products: Product[] = [
	// TechGear Pro Products
	{
		id: 'prod-1',
		vendorId: 'vendor-1',
		name: 'Wireless Noise-Canceling Headphones',
		description:
			'Premium over-ear headphones with active noise cancellation and 30-hour battery life',
		price: 29999,
		image: 'https://images.unsplash.com/photo-1505740420928-5e560c06d30e?w=500&q=80',
		category: 'Audio',
		sku: 'TGP-WH-001',
		maxQuantity: 10,
		inStock: true,
		tags: ['electronics', 'audio', 'wireless', 'premium']
	},
	{
		id: 'prod-2',
		vendorId: 'vendor-1',
		name: 'Smart Watch Pro',
		description: 'Fitness tracking smartwatch with heart rate monitor and GPS',
		price: 39999,
		image: 'https://images.unsplash.com/photo-1523275335684-37898b6baf30?w=500&q=80',
		category: 'Wearables',
		sku: 'TGP-SW-002',
		maxQuantity: 15,
		inStock: true,
		tags: ['electronics', 'wearables', 'fitness', 'smart']
	},
	{
		id: 'prod-3',
		vendorId: 'vendor-1',
		name: 'Portable Bluetooth Speaker',
		description: 'Waterproof speaker with 360-degree sound and 12-hour playtime',
		price: 7999,
		image: 'https://images.unsplash.com/photo-1608043152269-423dbba4e7e1?w=500&q=80',
		category: 'Audio',
		sku: 'TGP-SP-003',
		maxQuantity: 12,
		inStock: true,
		tags: ['electronics', 'audio', 'portable', 'waterproof']
	},

	// Artisan Crafts Co Products
	{
		id: 'prod-4',
		vendorId: 'vendor-2',
		name: 'Handwoven Ceramic Mug Set',
		description: 'Set of 4 artisan-crafted ceramic mugs with unique glaze patterns',
		price: 5999,
		image: 'https://images.unsplash.com/photo-1514228742587-6b1558fcca3d?w=500&q=80',
		category: 'Kitchenware',
		sku: 'ACC-MUG-004',
		maxQuantity: 8,
		inStock: true,
		tags: ['handmade', 'ceramic', 'kitchenware', 'artisan']
	},
	{
		id: 'prod-5',
		vendorId: 'vendor-2',
		name: 'Macrame Wall Hanging',
		description: 'Bohemian-style macrame wall art, handcrafted with natural cotton',
		price: 8999,
		image: 'https://images.unsplash.com/photo-1632761644913-0da6105863cb?w=500&q=80',
		category: 'Home Decor',
		sku: 'ACC-MAC-005',
		maxQuantity: 5,
		inStock: true,
		tags: ['handmade', 'decor', 'bohemian', 'wall-art']
	},
	{
		id: 'prod-6',
		vendorId: 'vendor-2',
		name: 'Leather Journal with Brass Clasp',
		description: 'Genuine leather-bound journal with hand-stitched binding and brass closure',
		price: 4999,
		image: 'https://images.unsplash.com/photo-1531346878377-a5be20888e57?w=500&q=80',
		category: 'Stationery',
		sku: 'ACC-JRN-006',
		maxQuantity: 2,
		inStock: true,
		tags: ['handmade', 'leather', 'journal', 'stationery']
	},

	// FitLife Essentials Products
	{
		id: 'prod-7',
		vendorId: 'vendor-3',
		name: 'Premium Yoga Mat',
		description: 'Eco-friendly TPE yoga mat with alignment marks and carrying strap',
		price: 6999,
		image: 'https://images.unsplash.com/photo-1601925260368-ae2f83cf8b7f?w=500&q=80',
		category: 'Fitness',
		sku: 'FLE-YGA-007',
		maxQuantity: 5,
		inStock: true,
		tags: ['fitness', 'yoga', 'eco-friendly', 'exercise']
	},
	{
		id: 'prod-8',
		vendorId: 'vendor-3',
		name: 'Resistance Bands Set',
		description: 'Set of 5 resistance bands with different tension levels and door anchor',
		price: 2999,
		image: 'https://images.unsplash.com/photo-1598289431512-b97b0917affc?w=500&q=80',
		category: 'Fitness',
		sku: 'FLE-RES-008',
		maxQuantity: 3,
		inStock: true,
		tags: ['fitness', 'resistance', 'exercise', 'portable']
	},
	{
		id: 'prod-9',
		vendorId: 'vendor-3',
		name: 'Stainless Steel Water Bottle',
		description: '32oz insulated water bottle keeps drinks cold for 24 hours',
		price: 3499,
		image: 'https://images.unsplash.com/photo-1602143407151-7111542de6e8?w=500&q=80',
		category: 'Hydration',
		sku: 'FLE-BTL-009',
		maxQuantity: 4,
		inStock: true,
		tags: ['fitness', 'hydration', 'insulated', 'eco-friendly']
	},

	// HomeStyle Living Products
	{
		id: 'prod-10',
		vendorId: 'vendor-4',
		name: 'Scented Candle Collection',
		description: 'Set of 3 soy wax candles with essential oils in modern concrete vessels',
		price: 4499,
		image: 'https://images.unsplash.com/photo-1643122966676-29e8597257f7?w=500&q=80',
		category: 'Home Fragrance',
		sku: 'HSL-CND-010',
		maxQuantity: 8,
		inStock: true,
		tags: ['home', 'candles', 'fragrance', 'soy']
	},
	{
		id: 'prod-11',
		vendorId: 'vendor-4',
		name: 'Minimalist Table Lamp',
		description: 'Modern desk lamp with touch dimming and warm LED light',
		price: 7999,
		image: 'https://images.unsplash.com/photo-1507473885765-e6ed057f782c?w=500&q=80',
		category: 'Lighting',
		sku: 'HSL-LMP-011',
		maxQuantity: 4,
		inStock: true,
		tags: ['home', 'lighting', 'modern', 'minimalist']
	},
	{
		id: 'prod-12',
		vendorId: 'vendor-4',
		name: 'Throw Pillow Set',
		description: 'Set of 2 decorative throw pillows with geometric patterns',
		price: 5499,
		image: 'https://images.unsplash.com/photo-1584100936595-c0654b55a2e2?w=500&q=80',
		category: 'Textiles',
		sku: 'HSL-PIL-012',
		maxQuantity: 5,
		inStock: true,
		tags: ['home', 'textiles', 'decor', 'pillows']
	}
]

// Helper Functions

export function getVendor(slug: string): Vendor | undefined {
	return vendors.find((v) => v.slug === slug)
}

export function getProductsByVendor(vendorId: string): Product[] {
	return products.filter((p) => p.vendorId === vendorId)
}

export function getProductsByVendorSlug(slug: string): Product[] {
	const vendor = getVendor(slug)
	if (!vendor) return []
	return getProductsByVendor(vendor.id)
}

export function getProduct(id: string): Product | undefined {
	return products.find((p) => p.id === id)
}

export function getAllVendors(): Vendor[] {
	return vendors
}

export function getAllProducts(): Product[] {
	return products
}

8. Componentes de UI do Carrinho

AddToCartButton

Este botão fornece feedback visual através de múltiplos estados: ocioso, adicionando, adicionado e erro.

Crie src/lib/cart/AddToCartButton.svelte:

<!-- src/lib/cart/AddToCartButton.svelte -->
<script lang="ts">
	import { getCartContext } from './cart-context.svelte'
	import type { CartProduct, CartItemOptions } from './types'

	interface Props {
		product: CartProduct
		quantity?: number
		options?: CartItemOptions
		class?: string
	}

	let { product, quantity = 1, options = {}, class: className = '' }: Props = $props()

	const cart = getCartContext()

	type ButtonState = 'idle' | 'adding' | 'added' | 'error'
	let buttonState = $state<ButtonState>('idle')
	let errorMessage = $state('')

	let isInCart = $derived(cart.hasItem(product.id, options))
	let cartQuantity = $derived(cart.getQuantity(product.id, options))

	async function handleAdd() {
		buttonState = 'adding'

		// Small delay for visual feedback
		await new Promise((resolve) => setTimeout(resolve, 200))

		const result = cart.addItem(product, quantity, options)

		if (result.success) {
			buttonState = 'added'
			setTimeout(() => {
				buttonState = 'idle'
			}, 2000)
		} else {
			buttonState = 'error'
			errorMessage = result.message ?? 'Could not add to cart'
			setTimeout(() => {
				buttonState = 'idle'
				errorMessage = ''
			}, 3000)
		}
	}
</script>

<button
	type="button"
	class="add-to-cart {className}"
	class:adding={buttonState === 'adding'}
	class:added={buttonState === 'added'}
	class:error={buttonState === 'error'}
	class:in-cart={isInCart && buttonState === 'idle'}
	onclick={handleAdd}
	disabled={buttonState === 'adding'}
>
	{#if buttonState === 'adding'}
		<span class="spinner" aria-hidden="true"></span>
		<span>Adding...</span>
	{:else if buttonState === 'added'}
		<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
			<polyline points="20 6 9 17 4 12" />
		</svg>
		<span>Added!</span>
	{:else if buttonState === 'error'}
		<span>{errorMessage}</span>
	{:else if isInCart}
		<span>In Cart ({cartQuantity})</span>
	{:else}
		<span>Add to Cart</span>
	{/if}
</button>

<style>
	.add-to-cart {
		display: inline-flex;
		align-items: center;
		justify-content: center;
		gap: 0.5rem;
		padding: 0.75rem 1.5rem;
		min-width: 140px;
		font-size: 0.9375rem;
		font-weight: 500;
		color: white;
		background-color: var(--color-primary, #3b82f6);
		border: none;
		border-radius: 8px;
		cursor: pointer;
		transition: all 0.2s ease;
	}

	.add-to-cart:hover:not(:disabled) {
		background-color: var(--color-primary-hover, #2563eb);
	}

	.add-to-cart:disabled {
		cursor: not-allowed;
		opacity: 0.8;
	}

	.add-to-cart.added {
		background-color: var(--color-success, #16a34a);
	}

	.add-to-cart.error {
		background-color: var(--color-error, #dc2626);
	}

	.add-to-cart.in-cart {
		background-color: var(--color-muted, #64748b);
	}

	.add-to-cart svg {
		width: 18px;
		height: 18px;
	}

	.spinner {
		width: 18px;
		height: 18px;
		border: 2px solid rgba(255, 255, 255, 0.3);
		border-top-color: white;
		border-radius: 50%;
		animation: spin 0.8s linear infinite;
	}

	@keyframes spin {
		to {
			transform: rotate(360deg);
		}
	}
</style>

CartIcon

Um ícone no cabeçalho com um badge mostrando a quantidade total.

Crie src/lib/cart/CartIcon.svelte:

<!-- src/lib/cart/CartIcon.svelte -->
<script lang="ts">
	import { ShoppingCart } from 'lucide-svelte'
	import { getCartContext } from './cart-context.svelte'

	interface Props {
		onclick?: () => void
	}

	let { onclick }: Props = $props()

	const cart = getCartContext()

	let badgeText = $derived(cart.totalQuantity > 99 ? '99+' : String(cart.totalQuantity))
</script>

<button
	type="button"
	class="cart-icon"
	{onclick}
	aria-label="Shopping cart with {cart.totalQuantity} items"
>
	<ShoppingCart size={24} stroke-width={2} aria-hidden="true" />

	{#if cart.totalQuantity > 0}
		<span class="badge" aria-hidden="true">
			{badgeText}
		</span>
	{/if}
</button>

<style>
	.cart-icon {
		position: relative;
		display: flex;
		align-items: center;
		justify-content: center;
		width: 44px;
		height: 44px;
		padding: 0;
		border: none;
		background: transparent;
		cursor: pointer;
		color: var(--color-foreground, #1e293b);
		transition: color 0.2s;
	}

	.cart-icon:hover {
		color: var(--color-primary, #3b82f6);
	}

	.cart-icon:focus-visible {
		outline: 2px solid var(--color-primary, #3b82f6);
		outline-offset: 2px;
		border-radius: 4px;
	}

	.badge {
		position: absolute;
		top: 4px;
		right: 4px;
		min-width: 18px;
		height: 18px;
		padding: 0 5px;
		font-size: 11px;
		font-weight: 600;
		line-height: 18px;
		text-align: center;
		color: white;
		background-color: var(--color-primary, #3b82f6);
		border-radius: 9px;
	}
</style>

QuantitySelector

Um controle +/- reutilizável com validação de entrada e limitação de valores.

Crie src/lib/cart/QuantitySelector.svelte:

<!-- src/lib/cart/QuantitySelector.svelte -->
<script lang="ts">
	interface Props {
		value?: number
		min?: number
		max?: number
		onchange?: (quantity: number) => void
		disabled?: boolean
		compact?: boolean
	}

	let {
		value = $bindable(1),
		min = 1,
		max,
		onchange,
		disabled = false,
		compact = false
	}: Props = $props()

	let canDecrement = $derived(value > min && !disabled)
	let canIncrement = $derived((!max || value < max) && !disabled)

	function decrement() {
		if (canDecrement) {
			value -= 1
			onchange?.(value)
		}
	}

	function increment() {
		if (canIncrement) {
			value += 1
			onchange?.(value)
		}
	}

	function handleInput(event: Event) {
		const input = event.target as HTMLInputElement
		let newValue = parseInt(input.value, 10)

		if (isNaN(newValue) || newValue < min) {
			newValue = min
		} else if (max && newValue > max) {
			newValue = max
		}

		value = newValue
		onchange?.(value)
	}
</script>

<div class="quantity-selector" class:disabled class:compact>
	<button
		type="button"
		class="qty-btn"
		onclick={decrement}
		disabled={!canDecrement}
		aria-label="Decrease quantity"
	>
		<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
			<line x1="5" y1="12" x2="19" y2="12" />
		</svg>
	</button>

	<input
		type="number"
		class="qty-input"
		bind:value
		{min}
		{max}
		{disabled}
		oninput={handleInput}
		aria-label="Quantity"
	/>

	<button
		type="button"
		class="qty-btn"
		onclick={increment}
		disabled={!canIncrement}
		aria-label="Increase quantity"
	>
		<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
			<line x1="12" y1="5" x2="12" y2="19" />
			<line x1="5" y1="12" x2="19" y2="12" />
		</svg>
	</button>
</div>

<style>
	.quantity-selector {
		display: inline-flex;
		align-items: center;
		border: 1px solid var(--color-border, #e2e8f0);
		border-radius: 8px;
		overflow: hidden;
	}

	.quantity-selector.disabled {
		opacity: 0.5;
	}

	.qty-btn {
		display: flex;
		align-items: center;
		justify-content: center;
		width: 36px;
		height: 36px;
		padding: 0;
		border: none;
		background: var(--color-surface, #f8fafc);
		cursor: pointer;
		transition: background-color 0.2s;
	}

	.compact .qty-btn {
		width: 28px;
		height: 28px;
	}

	.qty-btn:hover:not(:disabled) {
		background: var(--color-surface-hover, #e2e8f0);
	}

	.qty-btn:disabled {
		cursor: not-allowed;
		opacity: 0.4;
	}

	.qty-btn svg {
		width: 16px;
		height: 16px;
		color: var(--color-foreground, #1e293b);
	}

	.qty-input {
		width: 48px;
		height: 36px;
		padding: 0;
		border: none;
		border-left: 1px solid var(--color-border, #e2e8f0);
		border-right: 1px solid var(--color-border, #e2e8f0);
		text-align: center;
		font-size: 0.9375rem;
		font-weight: 500;
		background: white;
		appearance: textfield;
		-moz-appearance: textfield;
	}

	.qty-input::-webkit-outer-spin-button,
	.qty-input::-webkit-inner-spin-button {
		-webkit-appearance: none;
		margin: 0;
	}

	.qty-input:focus {
		outline: none;
		background: var(--color-primary-ring, rgba(59, 130, 246, 0.1));
	}
</style>

Observe o uso de $bindable — isso habilita a ligação bidirecional com bind:value do componente pai, ao mesmo tempo que permite que o componente atualize o valor internamente.

CartSummary

O componente de resumo do pedido com campo de entrada para código de desconto.

Crie src/lib/cart/CartSummary.svelte:

<!-- src/lib/cart/CartSummary.svelte -->
<script lang="ts">
	import { formatPrice } from '$lib/utils/formatting'
	import { Lightbulb } from 'lucide-svelte'
	import { getCartContext } from './cart-context.svelte'

	interface Props {
		showShipping?: boolean
		showDiscountInput?: boolean
		showBreakdown?: boolean
		showHints?: boolean
	}

	let {
		showShipping = true,
		showDiscountInput = true,
		showBreakdown = true,
		showHints = true
	}: Props = $props()

	const cart = getCartContext()

	let discountCode = $state('')
	let discountError = $state('')
	let showAllHints = $state(false)

	const discountHints = [
		{ code: 'SAVE10', description: '10% off' },
		{ code: 'SAVE20', description: '20% off orders $50+' },
		{ code: 'FLAT5', description: '$5 off' },
		{ code: 'WELCOME', description: '15% off' },
		{ code: 'FREESHIP', description: 'Free shipping' }
	]

	async function handleApplyDiscount() {
		discountError = ''
		const result = await cart.applyDiscount(discountCode)

		if (result.success) {
			discountCode = ''
		} else {
			discountError = result.error ?? 'Invalid code'
		}
	}

	function applyHintCode(code: string) {
		discountCode = code
		handleApplyDiscount()
	}
</script>

<div class="cart-summary">
	<h2 class="summary-title">Order Summary</h2>

	<dl class="summary-rows">
		{#if showBreakdown}
			<div class="summary-row">
				<dt>Subtotal ({cart.summary.totalQuantity} items)</dt>
				<dd>{formatPrice(cart.summary.subtotal)}</dd>
			</div>
		{/if}

		{#if cart.appliedDiscount}
			<div class="summary-row discount-row">
				<dt>
					Discount
					<span class="discount-code">({cart.appliedDiscount.code})</span>
					<button
						type="button"
						class="remove-discount"
						onclick={() => cart.removeDiscount()}
						aria-label="Remove discount"
					>
						x
					</button>
				</dt>
				<dd class="discount-amount">-{formatPrice(cart.summary.discount)}</dd>
			</div>
		{/if}

		{#if showShipping}
			<div class="summary-row">
				<dt>Shipping</dt>
				<dd>
					{#if cart.summary.shipping === 0}
						<span class="free-shipping">Free</span>
					{:else}
						{formatPrice(cart.summary.shipping)}
					{/if}
				</dd>
			</div>
		{/if}

		{#if showBreakdown}
			<div class="summary-row">
				<dt>Tax</dt>
				<dd>{formatPrice(cart.summary.tax)}</dd>
			</div>
		{/if}

		<div class="summary-row total-row">
			<dt>Total</dt>
			<dd class="total-amount">{formatPrice(cart.summary.total)}</dd>
		</div>
	</dl>

	{#if showDiscountInput && !cart.appliedDiscount}
		<div class="discount-form">
			<label for="discount-code" class="visually-hidden">Discount code</label>

			<div class="discount-input-group">
				<input
					type="text"
					id="discount-code"
					bind:value={discountCode}
					placeholder="Discount code"
					disabled={cart.isLoading}
				/>
				<button
					type="button"
					onclick={handleApplyDiscount}
					disabled={cart.isLoading || !discountCode.trim()}
				>
					{cart.isLoading ? 'Applying...' : 'Apply'}
				</button>
			</div>

			{#if discountError}
				<p class="discount-error" role="alert">{discountError}</p>
			{/if}

			{#if showHints}
				<div class="discount-hints">
					<button type="button" class="hints-toggle" onclick={() => (showAllHints = !showAllHints)}>
						<span class="hints-icon"><Lightbulb size={16} /></span>
						{showAllHints ? 'Hide' : 'Show'} demo codes
					</button>

					{#if showAllHints}
						<div class="hints-list">
							{#each discountHints as hint (hint.code)}
								<button type="button" class="hint-chip" onclick={() => applyHintCode(hint.code)}>
									<span class="hint-code">{hint.code}</span>
									<span class="hint-desc">{hint.description}</span>
								</button>
							{/each}
						</div>
					{/if}
				</div>
			{/if}
		</div>
	{/if}
</div>

Nota de estilização: Cada componente acima inclui blocos <style> com escopo. Por questões de brevidade neste artigo, alguns CSS foram omitidos. Consulte o código-fonte completo para os estilos completos.

9. Componentes de UI da Lista de Desejos

WishlistButton

Um botão de alternância com um ícone de coração.

Crie src/lib/wishlist/WishlistButton.svelte:

<!-- src/lib/wishlist/WishlistButton.svelte -->
<script lang="ts">
	import type { CartProduct } from '$lib/cart/types'
	import { Heart } from 'lucide-svelte'
	import { getWishlistContext } from './wishlist-context.svelte'

	interface Props {
		product: CartProduct
		showLabel?: boolean
	}

	let { product, showLabel = false }: Props = $props()

	const wishlist = getWishlistContext()

	let isInWishlist = $derived(wishlist.has(product.id))
</script>

<button
	type="button"
	class="wishlist-btn"
	class:active={isInWishlist}
	onclick={() => wishlist.toggle(product)}
	aria-label={isInWishlist ? 'Remove from wishlist' : 'Add to wishlist'}
>
	<Heart
		size={20}
		fill={isInWishlist ? 'currentColor' : 'none'}
		stroke-width={2}
		aria-hidden="true"
	/>

	{#if showLabel}
		<span>{isInWishlist ? 'Saved' : 'Save'}</span>
	{/if}
</button>

<style>
	.wishlist-btn {
		display: inline-flex;
		align-items: center;
		gap: 0.5rem;
		padding: 0.5rem;
		border: 1px solid #e2e8f0;
		background: white;
		border-radius: 8px;
		cursor: pointer;
		color: #64748b;
		transition: all 0.2s;
	}

	.wishlist-btn:hover,
	.wishlist-btn.active {
		color: #dc2626;
		border-color: #dc2626;
		background: #fef2f2;
	}
</style>

WishlistIcon

Crie src/lib/wishlist/WishlistIcon.svelte:

<!-- src/lib/wishlist/WishlistIcon.svelte -->
<script lang="ts">
	import { Heart } from 'lucide-svelte'
	import { getWishlistContext } from './wishlist-context.svelte'

	interface Props {
		onclick?: () => void
	}

	let { onclick }: Props = $props()

	const wishlist = getWishlistContext()
</script>

<button
	type="button"
	class="wishlist-icon"
	{onclick}
	aria-label="Wishlist with {wishlist.count} items"
>
	<Heart
		size={24}
		fill={wishlist.count > 0 ? 'currentColor' : 'none'}
		stroke-width={2}
		aria-hidden="true"
	/>

	{#if wishlist.count > 0}
		<span class="badge" aria-hidden="true">
			{wishlist.count}
		</span>
	{/if}
</button>

<style>
	.wishlist-icon {
		position: relative;
		display: flex;
		align-items: center;
		justify-content: center;
		width: 44px;
		height: 44px;
		padding: 0;
		border: none;
		background: transparent;
		cursor: pointer;
		color: var(--color-foreground, #1e293b);
		transition: color 0.2s;
	}

	.wishlist-icon:hover {
		color: var(--color-error, #dc2626);
	}

	.badge {
		position: absolute;
		top: 4px;
		right: 4px;
		min-width: 18px;
		height: 18px;
		padding: 0 5px;
		font-size: 11px;
		font-weight: 600;
		line-height: 18px;
		text-align: center;
		color: white;
		background-color: var(--color-error, #dc2626);
		border-radius: 9px;
	}
</style>

10. Componentes Compartilhados

ProductCard

Um componente de card flexível que utiliza snippets do Svelte 5 para slots personalizáveis.

Crie src/lib/components/ProductCard.svelte:

<!-- src/lib/components/ProductCard.svelte -->
<script lang="ts">
	import type { CartProduct } from '$lib/cart/types'
	import type { Snippet } from 'svelte'

	type ProductLike = CartProduct & {
		category?: string
		description?: string
		tags?: string[]
	}

	interface Props {
		product: ProductLike
		price: string
		variant?: 'product' | 'wishlist'
		category?: string
		description?: string
		tags?: string[]
		showTags?: boolean
		maxTags?: number
		image?: Snippet
		meta?: Snippet
		actions?: Snippet
	}

	let {
		product,
		price,
		variant = 'product',
		category = product.category,
		description = product.description,
		tags = product.tags ?? [],
		showTags = false,
		maxTags = 3,
		image,
		meta,
		actions
	}: Props = $props()

	const isWishlist = $derived(variant === 'wishlist')
	const visibleTags = $derived(showTags ? tags.slice(0, maxTags) : [])
</script>

<article class={isWishlist ? 'wishlist-card' : 'product-card'}>
	<div class={isWishlist ? 'card-image' : 'product-image'}>
		{@render image?.()}
	</div>

	<div class={isWishlist ? 'card-content' : 'product-info'}>
		{#if !isWishlist && category}
			<div class="product-category">{category}</div>
		{/if}

		<h3 class="product-name">{product.name}</h3>

		{#if isWishlist}
			{@render meta?.()}
		{:else}
			{#if description}
				<p class="product-description">{description}</p>
			{/if}
			{#if visibleTags.length > 0}
				<div class="product-tags">
					{#each visibleTags as tag (tag)}
						<span class="tag">{tag}</span>
					{/each}
				</div>
			{/if}
		{/if}

		{#if isWishlist}
			<div class="product-price wishlist-price">{price}</div>
			{#if actions}
				<div class="card-actions">
					{@render actions()}
				</div>
			{/if}
		{:else}
			<div class="product-footer">
				<div class="product-price">{price}</div>
				{@render actions?.()}
			</div>
		{/if}
	</div>
</article>

Snippets Explicados

Snippets são o substituto do Svelte 5 para slots. Eles permitem que os componentes pai passem conteúdo renderizável para os filhos:

<!-- Parent usage -->
<ProductCard {product} price={formatPrice(product.price)}>
	{#snippet image()}
		<img src={product.image} alt={product.name} />
		<div class="wishlist-action">
			<WishlistButton {product} />
		</div>
	{/snippet}

	{#snippet actions()}
		<AddToCartButton {product} />
	{/snippet}
</ProductCard>

O componente filho os renderiza com {@render image?.()} — o ?.() garante que não ocorra erro caso o snippet não tenha sido fornecido.

Crie src/lib/components/Header.svelte:

<!-- src/lib/components/Header.svelte -->
<script lang="ts">
	import { goto } from '$app/navigation'
	import CartIcon from '$lib/cart/CartIcon.svelte'
	import { ROUTES } from '$lib/config/routes'
	import WishlistIcon from '$lib/wishlist/WishlistIcon.svelte'
	import { ShoppingBag } from 'lucide-svelte'
</script>

<header class="site-header">
	<div class="header-content">
		<a href={ROUTES.HOME} class="logo">
			<ShoppingBag size={24} />
			<span>Hackpile Chronicles</span>
		</a>

		<nav class="main-nav">
			<a href={ROUTES.HOME}>Home</a>
			<a href={ROUTES.DEMO}>Demo</a>
		</nav>

		<div class="header-actions">
			<WishlistIcon onclick={() => goto(ROUTES.WISHLIST)} />
			<CartIcon onclick={() => goto(ROUTES.CART)} />
		</div>
	</div>
</header>

<style>
	.site-header {
		background: white;
		border-bottom: 1px solid var(--color-border, #e2e8f0);
		position: sticky;
		top: 0;
		z-index: 30;
	}

	.header-content {
		max-width: 1280px;
		margin: 0 auto;
		padding: 0 1.5rem;
		display: flex;
		align-items: center;
		justify-content: space-between;
		height: 64px;
	}

	.logo {
		display: flex;
		align-items: center;
		gap: 0.5rem;
		font-size: 1.25rem;
		font-weight: 700;
		color: var(--color-foreground, #1e293b);
		text-decoration: none;
	}

	.logo:hover {
		color: var(--color-primary, #3b82f6);
	}

	.main-nav {
		display: flex;
		gap: 2rem;
	}

	.main-nav a {
		color: var(--color-muted, #64748b);
		text-decoration: none;
		font-weight: 500;
	}

	.main-nav a:hover {
		color: var(--color-foreground, #1e293b);
	}

	.header-actions {
		display: flex;
		align-items: center;
		gap: 0.75rem;
	}

	@media (max-width: 640px) {
		.main-nav {
			display: none;
		}
	}
</style>

11. Conectar Layouts e Rotas

Layout Raiz

O layout raiz envolve toda a aplicação com ambos os providers.

Crie src/routes/+layout.svelte:

<!-- src/routes/+layout.svelte -->
<script lang="ts">
	import CartProvider from '$lib/cart/CartProvider.svelte'
	import WishlistProvider from '$lib/wishlist/WishlistProvider.svelte'
	import '../app.css'

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

<CartProvider taxRate={0.08} freeShippingThreshold={7500} currency="USD">
	<WishlistProvider>
		<main>
			{@render children()}
		</main>
	</WishlistProvider>
</CartProvider>

Layout de Demo

A seção de demo usa um reset de layout (+layout@.svelte) para sair do layout raiz e fornecer seu próprio contexto isolado com um cabeçalho.

Crie src/routes/demo/+layout@.svelte:

<!-- src/routes/demo/+layout@.svelte -->
<script lang="ts">
	import CartProvider from '$lib/cart/CartProvider.svelte'
	import Header from '$lib/components/Header.svelte'
	import WishlistProvider from '$lib/wishlist/WishlistProvider.svelte'
	import '../../app.css'

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

<CartProvider taxRate={0.08} freeShippingThreshold={7500} currency="USD">
	<WishlistProvider>
		<Header />
		<main class="demo-layout">
			{@render children()}
		</main>
	</WishlistProvider>
</CartProvider>

<style>
	.demo-layout {
		max-width: 1280px;
		margin: 0 auto;
		padding: 1.5rem;
	}
</style>

O sufixo @ no nome do arquivo instrui o SvelteKit a resetar a cadeia de layouts — esta página e seus filhos não herdarão o layout raiz.

12. Construir as Páginas

Página de Produtos

Crie src/routes/demo/products/+page.svelte:

<!-- src/routes/demo/products/+page.svelte -->
<script lang="ts">
	import AddToCartButton from '$lib/cart/AddToCartButton.svelte'
	import ProductCard from '$lib/components/ProductCard.svelte'
	import { getAllProducts } from '$lib/data/products'
	import { formatPrice } from '$lib/utils/formatting'
	import WishlistButton from '$lib/wishlist/WishlistButton.svelte'

	const products = getAllProducts()
</script>

<svelte:head>
	<title>Products - Hackpile Store</title>
</svelte:head>

<div class="products-page">
	<div class="page-header">
		<h1>All Products</h1>
		<p>Browse our complete collection from all vendors</p>
	</div>

	<div class="products-grid">
		{#each products as product (product.id)}
			<ProductCard {product} price={formatPrice(product.price)} showTags={false}>
				{#snippet image()}
					<img src={product.image} alt={product.name} />
					<div class="wishlist-action">
						<WishlistButton {product} />
					</div>
				{/snippet}

				{#snippet actions()}
					<AddToCartButton {product} />
				{/snippet}
			</ProductCard>
		{/each}
	</div>
</div>

<style>
	.products-page {
		max-width: 1280px;
		margin: 0 auto;
		padding: 2rem 1.5rem;
	}

	.page-header {
		margin-bottom: 3rem;
		text-align: center;
	}

	.page-header h1 {
		font-size: 2.5rem;
		font-weight: 700;
		margin-bottom: 0.5rem;
	}

	.page-header p {
		font-size: 1.125rem;
		color: var(--color-muted, #64748b);
	}

	.products-grid {
		display: grid;
		grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
		gap: 2rem;
	}
</style>

Página do Carrinho

Crie src/routes/demo/cart/+page.svelte:

<!-- src/routes/demo/cart/+page.svelte -->
<script lang="ts">
	import { getCartContext } from '$lib/cart/cart-context.svelte'
	import CartSummary from '$lib/cart/CartSummary.svelte'
	import QuantitySelector from '$lib/cart/QuantitySelector.svelte'
	import { ShoppingCart } from 'lucide-svelte'

	const cart = getCartContext()

	function formatPrice(cents: number): string {
		return new Intl.NumberFormat('en-US', {
			style: 'currency',
			currency: cart.currency
		}).format(cents / 100)
	}

	function handleQuantityChange(itemId: string, quantity: number) {
		if (quantity <= 0) {
			cart.removeItem(itemId)
		} else {
			cart.updateQuantity(itemId, quantity)
		}
	}
</script>

<svelte:head>
	<title>Shopping Cart - Hackpile Store</title>
</svelte:head>

<div class="cart-page">
	<div class="page-header">
		<h1>Shopping Cart</h1>
		{#if !cart.isEmpty}
			<p class="item-count">
				{cart.totalQuantity}
				{cart.totalQuantity === 1 ? 'item' : 'items'}
			</p>
		{/if}
	</div>

	{#if cart.isEmpty}
		<div class="empty-state">
			<div class="empty-icon">
				<ShoppingCart size={48} />
			</div>
			<h2>Your cart is empty</h2>
			<p>Browse products to get started</p>
			<a href="/demo/products" class="browse-btn">Browse Products</a>
		</div>
	{:else}
		<div class="cart-content">
			<div class="cart-items">
				<div class="items-header">
					<h2>Items</h2>
					<button class="clear-btn" onclick={() => cart.clearCart()}> Clear Cart </button>
				</div>

				<div class="items-list">
					{#each cart.items as item (item.id)}
						<article class="cart-item">
							<div class="item-image">
								{#if item.product.image}
									<img src={item.product.image} alt={item.product.name} />
								{:else}
									<div class="image-placeholder">
										{item.product.name.charAt(0)}
									</div>
								{/if}
							</div>

							<div class="item-details">
								<h3 class="item-name">{item.product.name}</h3>
								{#if item.product.sku}
									<p class="item-sku">SKU: {item.product.sku}</p>
								{/if}
								{#if Object.keys(item.options).length > 0}
									<div class="item-options">
										{#each Object.entries(item.options).filter(([_, v]) => v) as [key, value] (key)}
											<span class="option">{key}: {value}</span>
										{/each}
									</div>
								{/if}
								<p class="item-price">{formatPrice(item.product.price)} each</p>
							</div>

							<div class="item-actions">
								<QuantitySelector
									bind:value={item.quantity}
									max={item.product.maxQuantity}
									onchange={(qty) => handleQuantityChange(item.id, qty)}
								/>
								<div class="item-total">{formatPrice(item.lineTotal)}</div>
								<button
									class="remove-btn"
									onclick={() => cart.removeItem(item.id)}
									aria-label="Remove {item.product.name}"
								>
									Remove
								</button>
							</div>
						</article>
					{/each}
				</div>
			</div>

			<div class="cart-sidebar">
				<CartSummary showHints={true} />

				<div class="checkout-actions">
					<button class="checkout-btn">Proceed to Checkout</button>
					<a href="/demo/products" class="continue-shopping"> &larr; Continue Shopping </a>
				</div>
			</div>
		</div>
	{/if}
</div>

Página de Lista de Desejos

Crie src/routes/demo/wishlist/+page.svelte:

<!-- src/routes/demo/wishlist/+page.svelte -->
<script lang="ts">
	import { getCartContext } from '$lib/cart/cart-context.svelte'
	import ProductCard from '$lib/components/ProductCard.svelte'
	import { formatPrice } from '$lib/utils/formatting'
	import { getWishlistContext } from '$lib/wishlist/wishlist-context.svelte'
	import WishlistButton from '$lib/wishlist/WishlistButton.svelte'
	import { Heart } from 'lucide-svelte'

	const wishlist = getWishlistContext()
	const cart = getCartContext()

	function moveToCart(productId: string) {
		const item = wishlist.items.find((i) => i.product.id === productId)
		if (item) {
			cart.addItem(item.product)
			wishlist.remove(productId)
		}
	}
</script>

<svelte:head>
	<title>My Wishlist - Hackpile Store</title>
</svelte:head>

<div class="wishlist-page">
	<div class="page-header">
		<h1>Your Wishlist</h1>
		<p>Your saved items from all vendors</p>
	</div>

	{#if wishlist.isEmpty}
		<div class="empty-state">
			<div class="empty-icon">
				<Heart size={48} />
			</div>
			<h2>Your wishlist is empty</h2>
			<p>Save your favorite products to come back to them later</p>
			<a href="/demo/products" class="browse-btn">Browse Products</a>
		</div>
	{:else}
		<div class="wishlist-header">
			<p class="item-count">
				{wishlist.count}
				{wishlist.count === 1 ? 'item' : 'items'}
			</p>
			<button class="clear-btn" onclick={() => wishlist.clear()}> Clear All </button>
		</div>

		<div class="wishlist-grid">
			{#each wishlist.items as { product } (product.id)}
				<ProductCard {product} price={formatPrice(product.price)} variant="wishlist">
					{#snippet image()}
						{#if product.image}
							<img src={product.image} alt={product.name} />
						{:else}
							<div class="image-placeholder">
								{product.name.charAt(0)}
							</div>
						{/if}
						<div class="wishlist-action">
							<WishlistButton {product} />
						</div>
					{/snippet}

					{#snippet meta()}
						{#if product.sku}
							<p class="product-sku">SKU: {product.sku}</p>
						{/if}
					{/snippet}

					{#snippet actions()}
						<button class="add-to-cart-btn" onclick={() => moveToCart(product.id)}>
							Add to Cart
						</button>
						<button class="view-btn" onclick={() => (window.location.href = '/demo/products')}>
							View Product
						</button>
					{/snippet}
				</ProductCard>
			{/each}
		</div>
	{/if}
</div>

13. API de Código de Desconto

Crie um endpoint de API do SvelteKit para validação de desconto no lado do servidor.

Crie src/routes/api/coupons/validate/+server.ts:

// src/routes/api/coupons/validate/+server.ts

import { json } from '@sveltejs/kit'
import type { RequestHandler } from './$types'

/**
 * Demo discount codes.
 * In a real app, these would come from a database.
 */
const DISCOUNT_CODES: Record<
	string,
	{
		type: 'percentage' | 'fixed'
		value: number
		minOrder?: number
		description: string
	}
> = {
	SAVE10: {
		type: 'percentage',
		value: 10,
		description: '10% off your order'
	},
	SAVE20: {
		type: 'percentage',
		value: 20,
		minOrder: 5000, // $50 minimum
		description: '20% off orders over $50'
	},
	FLAT5: {
		type: 'fixed',
		value: 500, // $5 off
		description: '$5 off your order'
	},
	WELCOME: {
		type: 'percentage',
		value: 15,
		description: '15% off for new customers'
	},
	FREESHIP: {
		type: 'fixed',
		value: 599, // Covers standard shipping
		description: 'Free shipping ($5.99 value)'
	}
}

export const POST: RequestHandler = async ({ request }) => {
	try {
		const { code, subtotal } = await request.json()

		if (!code || typeof code !== 'string') {
			return json({ message: 'Please enter a discount code' }, { status: 400 })
		}

		const normalizedCode = code.trim().toUpperCase()
		const discount = DISCOUNT_CODES[normalizedCode]

		if (!discount) {
			return json(
				{
					message: 'Invalid discount code. Try: SAVE10, SAVE20, FLAT5, WELCOME, or FREESHIP'
				},
				{ status: 400 }
			)
		}

		// Check minimum order requirement
		if (discount.minOrder && subtotal < discount.minOrder) {
			const minOrderFormatted = (discount.minOrder / 100).toFixed(2)
			return json(
				{ message: `This code requires a minimum order of $${minOrderFormatted}` },
				{ status: 400 }
			)
		}

		// Calculate the applied amount
		let appliedAmount: number
		if (discount.type === 'percentage') {
			appliedAmount = Math.round(subtotal * (discount.value / 100))
		} else {
			appliedAmount = Math.min(discount.value, subtotal)
		}

		return json({
			code: normalizedCode,
			type: discount.type,
			value: discount.value,
			appliedAmount,
			description: discount.description
		})
	} catch {
		return json({ message: 'Failed to validate discount code' }, { status: 500 })
	}
}

14. Marketplace Multi-Fornecedor

O marketplace demonstra o padrão mais poderoso desta aplicação: provedores de contexto aninhados. Cada página de fornecedor envolve seu conteúdo em um novo CartProvider com configuração específica do fornecedor, isolando completamente seu carrinho do global.

Carregamento do Servidor do Layout de Fornecedor

Crie src/routes/demo/(vendor)/marketplace/[vendor]/+layout.server.ts:

// src/routes/demo/(vendor)/marketplace/[vendor]/+layout.server.ts

import { error } from '@sveltejs/kit'
import { getVendor } from '$lib/data/products'
import type { LayoutServerLoad } from './$types'

export const load: LayoutServerLoad = ({ params }) => {
	const vendor = getVendor(params.vendor)

	if (!vendor) {
		error(404, `Vendor "${params.vendor}" not found`)
	}

	return { vendor }
}

Layout de Fornecedor (Contexto Aninhado)

É aqui que a mágica acontece. O layout de fornecedor cria novas instâncias de CartProvider e WishlistProvider com chaves de armazenamento e configurações específicas do fornecedor. Estas substituem os contextos pai para todos os componentes filhos.

Crie src/routes/demo/(vendor)/marketplace/[vendor]/+layout.svelte:

<!-- src/routes/demo/(vendor)/marketplace/[vendor]/+layout.svelte -->
<script lang="ts">
	import CartProvider from '$lib/cart/CartProvider.svelte'
	import VendorHeader from '$lib/components/VendorHeader.svelte'
	import WishlistProvider from '$lib/wishlist/WishlistProvider.svelte'
	import type { LayoutData } from './$types'

	let { data, children }: { data: LayoutData; children: any } = $props()
</script>

<!-- Vendor-specific cart AND wishlist (nested, overrides parent contexts) -->
<CartProvider
	storageKey="{data.vendor.id}-cart"
	currency={data.vendor.currency}
	taxRate={data.vendor.taxRate}
	shippingCost={data.vendor.shippingCost}
>
	<WishlistProvider storageKey="{data.vendor.id}-wishlist">
		<VendorHeader vendor={data.vendor} />

		<div class="vendor-layout">
			<div class="vendor-info-banner">
				<span class="vendor-badge">{data.vendor.currency}</span>
				<span class="vendor-detail">
					Tax: {(data.vendor.taxRate * 100).toFixed(1)}%
				</span>
				<span class="vendor-detail">
					Shipping: ${(data.vendor.shippingCost / 100).toFixed(2)}
				</span>
			</div>

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

<style>
	.vendor-layout {
		max-width: 1280px;
		margin: 0 auto;
		padding: 1.5rem;
	}

	.vendor-info-banner {
		display: flex;
		align-items: center;
		gap: 1rem;
		padding: 0.75rem 1rem;
		background: var(--color-surface, #f8fafc);
		border: 1px solid var(--color-border, #e2e8f0);
		border-radius: 8px;
		margin-bottom: 1.5rem;
		font-size: 0.875rem;
	}

	.vendor-badge {
		padding: 0.25rem 0.5rem;
		background: var(--color-primary, #3b82f6);
		color: white;
		border-radius: 4px;
		font-weight: 600;
		font-size: 0.75rem;
	}

	.vendor-detail {
		color: var(--color-muted, #64748b);
	}
</style>

Como Funciona o Isolamento de Contexto

Quando você aninha componentes CartProvider, o provider interno cria um novo contexto usando a mesma chave Symbol('cart'). A API de Contexto do Svelte utiliza o ancestral mais próximo, portanto todos os componentes filhos que chamarem getCartContext() receberão o carrinho do fornecedor — não o global.

Root Layout
└── CartProvider (storageKey="cart")         ← Global cart
    └── WishlistProvider (storageKey="wishlist")
        └── Demo Layout
            └── Products Page               ← Uses global cart
            └── Cart Page                   ← Uses global cart
            └── Vendor Layout
                └── CartProvider (storageKey="vendor-1-cart")  ← Vendor cart
                    └── WishlistProvider (storageKey="vendor-1-wishlist")
                        └── Vendor Products ← Uses vendor-1 cart
                        └── Vendor Cart     ← Uses vendor-1 cart

Os dados de cada fornecedor persistem de forma independente no localStorage sob chaves como vendor-1-cart, vendor-2-cart, etc.

Utilitário de Resumo de Carrinhos por Fornecedor

Para exibir uma visão geral entre fornecedores (por exemplo, na página índice do marketplace), lemos diretamente do localStorage já que os contextos de fornecedor não estão montados nessa página.

Crie src/lib/cart/vendor-carts.svelte.ts:

// src/lib/cart/vendor-carts.svelte.ts

import { browser } from '$app/environment'
import { vendors, type Vendor } from '$lib/data/products'
import type { CartItem } from './types'
import type { WishlistItem } from '$lib/wishlist/types'

export interface VendorSummary {
	vendor: Vendor
	cart: {
		items: CartItem[]
		itemCount: number
		totalQuantity: number
		subtotal: number
	}
	wishlist: {
		items: WishlistItem[]
		count: number
	}
}

export function createVendorSummaries() {
	let summaries = $state<VendorSummary[]>([])
	let isLoaded = $state(false)

	function loadFromStorage() {
		if (!browser) return

		const result: VendorSummary[] = []

		for (const vendor of Object.values(vendors)) {
			let cartItems: CartItem[] = []
			try {
				const cartData = localStorage.getItem(`${vendor.id}-cart`)
				if (cartData) {
					const parsed = JSON.parse(cartData)
					cartItems = Array.isArray(parsed.items) ? parsed.items : []
				}
			} catch {
				// Invalid data, skip
			}

			let wishlistItems: WishlistItem[] = []
			try {
				const wishlistData = localStorage.getItem(`${vendor.id}-wishlist`)
				if (wishlistData) {
					wishlistItems = JSON.parse(wishlistData) || []
				}
			} catch {
				// Invalid data, skip
			}

			const totalQuantity = cartItems.reduce((sum, item) => sum + item.quantity, 0)
			const subtotal = cartItems.reduce((sum, item) => sum + item.lineTotal, 0)

			result.push({
				vendor,
				cart: {
					items: cartItems,
					itemCount: cartItems.length,
					totalQuantity,
					subtotal
				},
				wishlist: {
					items: wishlistItems,
					count: wishlistItems.length
				}
			})
		}

		summaries = result
		isLoaded = true
	}

	if (browser) {
		loadFromStorage()
		window.addEventListener('storage', loadFromStorage)
	}

	return {
		get summaries() {
			return summaries
		},
		get isLoaded() {
			return isLoaded
		},
		get totalCartItems() {
			return summaries.reduce((sum, s) => sum + s.cart.totalQuantity, 0)
		},
		get totalWishlistItems() {
			return summaries.reduce((sum, s) => sum + s.wishlist.count, 0)
		},
		get vendorsWithItems() {
			return summaries.filter((s) => s.cart.itemCount > 0 || s.wishlist.count > 0)
		},
		refresh: loadFromStorage
	}
}

16. Sincronização de Carrinho no Lado do Servidor

Para usuários autenticados, você vai querer sincronizar o carrinho com seu backend. Isso permite a persistência do carrinho entre dispositivos e a recuperação de carrinhos abandonados.

O principal desafio é lidar com a mesclagem quando um usuário faz login. Ele pode ter itens em seu carrinho local (adicionados enquanto estava deslogado) e itens no servidor (adicionados a partir de outro dispositivo). Você precisa de uma estratégia para reconciliar essas duas fontes.

Crie uma factory de contexto de carrinho aprimorada que adiciona capacidades de sincronização com o servidor:

// Enhanced cart context with server sync
import { browser } from '$app/environment'

interface SyncOptions {
	userId?: string | null
	syncEndpoint?: string
	debounceMs?: number
}

export function createSyncedCartContext(
	cartOptions: CartOptions = {},
	syncOptions: SyncOptions = {}
): CartContext {
	const { userId, syncEndpoint = '/api/cart', debounceMs = 1000 } = syncOptions

	// ... existing cart implementation ...

	// Debounced server sync
	let syncTimeout: ReturnType<typeof setTimeout> | null = null

	$effect(() => {
		if (!browser || !userId) return

		// Track items and discount for sync
		const currentItems = items
		const currentDiscount = appliedDiscount

		// Cancel pending sync
		if (syncTimeout) {
			clearTimeout(syncTimeout)
		}

		// Debounce sync to server
		syncTimeout = setTimeout(async () => {
			try {
				await fetch(syncEndpoint, {
					method: 'POST',
					headers: { 'Content-Type': 'application/json' },
					body: JSON.stringify({
						items: currentItems,
						discount: currentDiscount
					})
				})
			} catch (error) {
				console.error('Failed to sync cart to server:', error)
			}
		}, debounceMs)
	})

	// Load from server on mount (for logged-in users)
	$effect(() => {
		if (!browser || !userId) return

		async function loadServerCart() {
			try {
				const response = await fetch(syncEndpoint)
				if (response.ok) {
					const serverCart = await response.json()
					mergeServerCart(serverCart)
				}
			} catch (error) {
				console.error('Failed to load cart from server:', error)
			}
		}

		loadServerCart()
	})

	function mergeServerCart(serverCart: { items: CartItem[]; discount?: AppliedDiscount | null }) {
		// Strategy: Server wins for conflicts, keep local-only items
		const serverIds = new Set(serverCart.items.map((i) => i.id))
		const localOnly = items.filter((i) => !serverIds.has(i.id))

		items = [
			...serverCart.items.map((item) => ({
				...item,
				addedAt: new Date(item.addedAt)
			})),
			...localOnly
		]

		if (serverCart.discount) {
			appliedDiscount = serverCart.discount
		}
	}

	// ... rest of context implementation ...
}

Por Que Esta Estratégia de Mesclagem?

A função de mesclagem acima usa a estratégia "o servidor vence nos conflitos, manter adições locais":

Itens presentes tanto no servidor quanto localmente: A versão do servidor prevalece (ela pode ter alterações de quantidade mais recentes provenientes de outro dispositivo)
Itens apenas no servidor: Mantidos (adicionados a partir de outro dispositivo)
Itens apenas localmente: Mantidos (adicionados enquanto deslogado, o usuário espera que persistam)

Este é um bom padrão padrão porque preserva a intenção do usuário — tudo que foi adicionado localmente permanece, e as alterações remotas são respeitadas. Para uso em produção, você provavelmente adicionaria timestamps a cada item e usaria "última escrita vence" para conflitos, ou solicitaria ao usuário que resolva as diferenças.

Por Que Usar Debounce?

Sem debounce, cada alteração de quantidade dispararia uma requisição de rede. Se um usuário clicar no botão "+" cinco vezes rapidamente, isso resulta em cinco requisições POST. O debounce de 1 segundo agrupa essas em uma única requisição, reduzindo a carga no servidor e evitando condições de corrida onde uma requisição mais antiga chega após uma mais recente.

17. Erros Comuns e Anti-Padrões

Erro 1: Usar Apenas o ID do Produto como ID do Item do Carrinho

// WRONG: Same product with different options overwrites
items.push({
	id: product.id, // Collision when same product, different size!
	product,
	options: { size: 'Large' },
	quantity: 1
})

// CORRECT: Generate unique ID from product + options
const itemId = generateItemId(product.id, options)
// "shirt-123__size:Large|color:Blue"

Por que isso importa: Em qualquer loja com variantes, o mesmo produto em tamanhos ou cores diferentes deve corresponder a linhas separadas no carrinho. O usuário espera que "Camiseta Azul (G)" e "Camiseta Azul (M)" sejam rastreadas de forma independente. Usar apenas o ID do produto as mescla em uma única linha, perdendo silenciosamente as informações de variante.

Erro 2: Mutando Objetos de Produto

// WRONG: Mutates the original product
function addItem(product) {
	product.quantity = 1 // Modifies original!
	product.addedAt = new Date()
	items.push(product)
}

// CORRECT: Store product as reference, metadata separately
function addItem(product) {
	items.push({
		id: generateItemId(product.id, {}),
		product, // Reference only — never modified
		quantity: 1,
		addedAt: new Date(),
		lineTotal: product.price
	})
}

Por que isso importa: Se você mutar o objeto de produto, todo componente que mantém uma referência a esse produto verá a mutação. Um card de listagem de produto de repente tem uma propriedade quantity. Um resultado de pesquisa agora tem addedAt. Isso cria bugs difíceis de rastrear onde partes não relacionadas da UI se comportam de forma inesperada.

Erro 3: Rastreamento Manual do Total

// WRONG: Manual tracking gets out of sync
let total = $state(0)

function addItem(product) {
	items.push(product)
	total += product.price // Breaks when quantity changes!
}

function removeItem(id) {
	// Forgot to update total here!
	items = items.filter((i) => i.id !== id)
}

// CORRECT: Use $derived for all computed values
const total = $derived(items.reduce((sum, item) => sum + item.lineTotal, 0))
// Automatically correct, always

Por que isso importa: O rastreamento manual cria bugs de sincronização. Toda operação que altera itens também deve atualizar o total, e é fácil esquecer uma. Com $derived, o total é sempre computado a partir da fonte da verdade (o array de itens). Não há como ele ficar fora de sincronia.

Erro 4: Ignorar Limites de Estoque

// WRONG: No validation
function addItem(product, quantity) {
	items.push({ product, quantity }) // User adds 1000 items!
}

// CORRECT: Validate against maxQuantity
function addItem(product, quantity) {
	const maxQty = product.maxQuantity ?? Infinity
	if (quantity > maxQty) {
		return { success: false, error: 'MAX_QUANTITY_EXCEEDED' }
	}
	// ...
}

Por que isso importa: Sem validação de estoque, usuários podem adicionar mais itens do que você tem em inventário. Isso leva a falhas no atendimento, clientes insatisfeitos e custos com reembolsos. O padrão de objeto de resultado torna a falha explícita — o componente que chama deve lidar com a possibilidade de que a adição falhou.

Erro 5: Sobrescrever o Armazenamento Antes de Carregar

// WRONG: Persists empty cart, overwriting saved data
let items = $state<CartItem[]>([])

$effect(() => {
	if (browser) {
		// Runs immediately with empty items!
		localStorage.setItem('cart', JSON.stringify(items))
	}
})

// CORRECT: Track initialization state
let items = $state<CartItem[]>([])
let isInitialized = $state(false)

$effect.pre(() => {
	if (!browser || isInitialized) return
	items = loadFromStorage()
	isInitialized = true
})

$effect(() => {
	if (browser && isInitialized) {
		localStorage.setItem('cart', JSON.stringify(items))
	}
})

Por que isso importa: O $effect de salvamento é executado assim que o componente é montado. Se você ainda não carregou os dados persistidos, ele salva o estado padrão vazio, deletando permanentemente o carrinho do usuário. O guard isInitialized garante que carregamos primeiro, depois habilitamos o salvamento. Este é o bug de persistência mais comum em aplicações Svelte 5.

18. Considerações de Performance

Carrinhos de compras podem crescer bastante, e implementações mal otimizadas causam lag visível na UI. Aqui estão estratégias para manter seu carrinho rápido.

Minimize Re-renderizações com Valores Derivados Separados

Estruture seus valores derivados como computações independentes em vez de um único objeto grande:

// Less efficient: Every item change recalculates everything
const summary = $derived({
	itemCount: items.length,
	total: items.reduce((sum, i) => sum + i.lineTotal, 0)
	// ... more calculations
})

// Better: Separate derived values for independent concerns
const itemCount = $derived(items.length)
const subtotal = $derived(items.reduce((sum, i) => sum + i.lineTotal, 0))
const shipping = $derived(subtotal >= threshold ? 0 : shippingCost)
// Components only re-render when their specific values change

Por que isso importa: Quando os valores $derived são separados, a reatividade refinada do Svelte significa que um componente que só lê itemCount não será re-renderizado quando shipping mudar. Com um único objeto de resumo, todo consumidor é re-renderizado a cada mudança porque a referência do objeto muda.

Em nossa implementação, sim expomos um objeto summary por conveniência, mas os valores derivados individuais (itemCount, totalQuantity, isEmpty) também estão disponíveis para componentes que precisam apenas de um dado.

Debounce na Persistência

Não salve no localStorage a cada tecla digitada nos inputs de quantidade:

let saveTimeout: ReturnType<typeof setTimeout> | null = null

$effect(() => {
	if (!browser || !isInitialized) return

	const data = { items, discount: appliedDiscount }

	if (saveTimeout) clearTimeout(saveTimeout)

	saveTimeout = setTimeout(() => {
		localStorage.setItem(storageKey, JSON.stringify(data))
	}, 300)
})

Por que isso importa: localStorage.setItem é síncrono e bloqueia a thread principal. Para um carrinho com muitos itens, serializar para JSON e escrever pode levar vários milissegundos. Se o usuário altera quantidades rapidamente, isso se acumula. Um debounce de 300ms agrupa mudanças rápidas em uma única escrita.

Nota: Nossa implementação atual salva de forma síncrona (sem debounce) por simplicidade. Para carrinhos com 50+ itens, adicionar debounce passa a valer a pena.

Carregamento Lazy do Drawer do Carrinho

Não renderize o drawer do carrinho até que seja aberto:

{#if drawerOpen}
	<!-- Only renders and mounts when needed -->
	<CartDrawer onclose={() => (drawerOpen = false)} />
{/if}

Por que isso importa: O drawer do carrinho frequentemente inclui componentes complexos (seletores de quantidade, formulários de desconto, cálculos de resumo). Renderizá-lo em segundo plano desperdiça memória e ciclos de CPU. Os blocos {#if} do Svelte desmontam completamente o conteúdo quando falso, então os componentes não existem até que sejam necessários.

Use Blocos Each com Chave

Sempre utilize chave nos seus blocos {#each} ao renderizar itens do carrinho:

{#each cart.items as item (item.id)}
	<CartItemRow {item} />
{/each}

Por que isso importa: Sem uma chave, o Svelte usa diff baseado em índice. Quando você remove o segundo item de uma lista de cinco, o Svelte pensa que os itens 2-4 todos mudaram (porque seus índices foram deslocados). Com uma chave, o Svelte sabe exatamente qual nó do DOM remover. Isso importa especialmente durante animações ou quando os itens têm estado interno.

Com a performance abordada, vamos recapitular os primitivos do Svelte 5 que tornaram essa arquitetura possível.

19. Recapitulação dos Principais Padrões do Svelte 5

1. `$state` — Variáveis Reativas

let items = $state<CartItem[]>([])
let isLoading = $state(false)

Substitui as declarações reativas let do Svelte 4. Qualquer mutação em variáveis $state dispara atualizações na UI.

2. `$derived` — Valores Computados

const itemCount = $derived(items.length)
const isEmpty = $derived(items.length === 0)

Substitui os statements reativos $:. Recomputa automaticamente quando as dependências mudam.

3. `$derived.by` — Lógica Derivada Complexa

const discountAmount = $derived.by(() => {
	if (!appliedDiscount) return 0
	if (appliedDiscount.type === 'fixed') {
		return Math.min(appliedDiscount.value, subtotal)
	}
	return Math.round(subtotal * (appliedDiscount.value / 100))
})

Use .by() quando a derivação precisar de mais do que uma única expressão.

4. `$effect` — Efeitos Colaterais

$effect(() => {
	if (!browser || !isInitialized) return
	localStorage.setItem(storageKey, JSON.stringify(data))
})

Executa sempre que suas dependências rastreadas mudam. Perfeito para persistência, logging ou manipulação do DOM.

5. `$effect.pre` — Efeitos Pré-renderização

$effect.pre(() => {
	if (!browser || isInitialized) return
	loadFromStorage()
})

Executa antes das atualizações do DOM. Usado aqui para carregar dados persistidos antes da primeira renderização.

6. `$props()` e `$bindable`

let { value = $bindable(1), min = 1, max, onchange }: Props = $props()

$props() declara as props do componente. $bindable habilita a vinculação bidirecional com bind:value.

7. API de Contexto com Symbols

const CART_KEY = Symbol('cart')

// In provider
setContext(CART_KEY, context)

// In consumer
getContext(CART_KEY)

Symbols evitam colisões de chaves. getContext retorna o valor do ancestral mais próximo que chamou setContext com a mesma chave.

8. Propriedades Getter para Contexto Reativo

const context = {
	get items() {
		return items
	},
	get isEmpty() {
		return isEmpty
	}
	// ...
}

Getters garantem que os consumidores sempre leiam o valor reativo atual em vez de um snapshot desatualizado.

9. Snippets (Substitui Slots)

<!-- Parent -->
<ProductCard {product} price={formatPrice(product.price)}>
	{#snippet image()}
		<img src={product.image} alt={product.name} />
	{/snippet}
</ProductCard>

<!-- Child -->
{@render image?.()}

Snippets são tipados, combináveis e mais flexíveis do que os slots do Svelte 4.

10. `untrack` — Prevenir Rastreamento de Dependências

untrack(() => {
	createCartContext({ storageKey, currency, taxRate })
})

Evita o rastreamento reativo dentro do callback. Usado para garantir que o contexto seja criado uma única vez com os valores iniciais.

Conclusão

O carrinho de compras exemplifica como o contexto transforma o gerenciamento de estado complexo em algo gerenciável e intuitivo. Um carrinho toca quase todas as partes de uma aplicação de e-commerce — páginas de produto precisam adicionar itens, cabeçalhos precisam exibir contagens, cards de produto precisam de indicadores "no carrinho", e fluxos de checkout precisam do conteúdo completo do carrinho. Sem contexto, você teria que passar dados do carrinho e funções de atualização por dezenas de componentes intermediários. Com contexto, qualquer componente em qualquer lugar simplesmente chama getCartContext() e obtém tudo o que precisa.

O que torna esta implementação poderosa é a interação entre os primitivos reativos do Svelte 5. A rune $state mantém o array de itens, tornando-o reativo. A rune $derived calcula totais, impostos, frete e descontos — valores que se recalculam automaticamente quando os itens mudam e permanecem consistentes em todos os componentes. A rune $effect gerencia a persistência, salvando no localStorage sempre que o carrinho muda, sem exigir chamadas explícitas de salvamento. Cada primitivo faz uma coisa bem, e juntos criam um sistema onde as mudanças se propagam automaticamente das ações do usuário, passando pelos cálculos, até a UI e o armazenamento.

Os objetos de resultado para operações merecem atenção especial. Em vez de lançar erros ou retornar simples booleanos, métodos como addItem retornam resultados estruturados com códigos de erro específicos. Isso torna o tratamento de erros explícito — quem chama deve reconhecer que operações podem falhar — e type-safe — o TypeScript garante que todos os casos de erro sejam tratados. O mesmo padrão se aplica a qualquer contexto com operações que podem falhar: erros de validação, falhas de API ou violações de regras de negócio se beneficiam de resultados explícitos e tipados.

A natureza hierárquica do contexto habilita padrões poderosos como isolamento de carrinho por escopo. Um marketplace pode ter carrinhos completamente separados para cada fornecedor, cada um com sua própria chave de armazenamento, moeda e configuração de impostos. Os componentes não sabem em qual carrinho estão — eles simplesmente chamam getCartContext() e obtêm o mais próximo. Esse mesmo padrão se estende a múltiplos tipos de carrinho (lista de desejos, listas de comparação), sincronização com o servidor e qualquer outra variação que sua aplicação requeira.

Principais Conclusões

Construir um carrinho de compras com contexto demonstra como o sistema de reatividade do Svelte 5 cria um gerenciamento de estado elegante e de fácil manutenção:

Contexto em vez de Stores Globais: O contexto oferece segurança para SSR, isolamento de requisições, estado por escopo e testabilidade. Stores globais vazam estado entre requisições e não conseguem definir escopo para diferentes seções da sua aplicação.

Estado Reativo com $state mantém os itens do carrinho e o desconto. Quando esses mudam, tudo que depende deles é atualizado automaticamente — nenhuma sincronização manual necessária.

Cálculos Derivados com $derived computam totais, impostos e frete. Eles recalculam apenas quando suas dependências mudam, e todos os componentes veem os mesmos valores consistentes.

Persistência Automática com $effect salva o carrinho no localStorage sempre que itens ou descontos mudam. O efeito rastreia suas próprias dependências e executa quando necessário.

Objetos de Resultado para Operações tornam o tratamento de erros explícito e type-safe. Limites de estoque, erros de validação e outras falhas retornam resultados estruturados que quem chama deve tratar.

Isolamento por Escopo através de provedores aninhados habilita marketplaces multi-fornecedor, plataformas multi-tenant e qualquer arquitetura que requeira instâncias de carrinho separadas com configurações diferentes.

Aplique esses mesmos princípios a qualquer estado complexo que você precise compartilhar em toda a sua aplicação. A combinação de primitivos reativos e contexto cria sistemas que são ao mesmo tempo poderosos e de fácil manutenção.