Por Que Carrinhos de Compras São Difíceis

Um carrinho de compras exige bastante do gerenciamento de estado: muitas páginas o leem e escrevem, os totais devem permanecer 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 de SSR, o escopo multi-tenant e a confiabilidade dos testes.

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

Por Que Context para Carrinhos?

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

Considere estes 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 lojas virtuais
Portais B2B: Departamentos diferentes 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 isolado e com escopo 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 do 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 obtém um context isolado.

Isolamento com Escopo: O context flui para baixo pela árvore de componentes. Diferentes seções do seu app podem ter contextos de carrinho completamente distintos por meio do aninhamento de providers com configurações diferentes.

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 Marketplaces é o carrinho unificado. Por quê? É um modelo mental mais simples que facilita tanto a experiência do usuário quanto 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 por um context específico do vendedor. Providers aninhados substituem os contextos pais, 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 na mesma entrega
Fulfillment diferente: Cada vendedor envia separadamente com logística incompatível
Processadores de pagamento diferentes: Cada vendedor gerencia seus próprios pagamentos
B2B atacado: Termos, contratos e pedidos mínimos diferentes por fornecedor
Lojas 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 as 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 suportar. Pensar nos requisitos antecipadamente leva a um design de API melhor.

Requisitos Principais

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 recarregamentos de página, sincronizar opcionalmente com o servidor
Consultas	Verificar conteúdo, obter quantidades	Buscas eficientes para o estado da UI

Decisões de Modelagem de Dados

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

Identidade do Item: Um ID de produto sozinho não é suficiente quando o 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 somado às opções de variante.

Armazenamento de Preços: Armazenar preços em centavos como inteiros evita problemas de precisão com ponto flutuante. Um preço de $19.99 se torna 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 controlada 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: As 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ê construirá uma aplicação de carrinho de compras completa usando a API de Context e as runes do Svelte 5. O projeto cobre 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 o roteamento do 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

Aqui está 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. Cada valor monetário é armazenado em centavos para evitar problemas com 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?

Observe que addItem retorna AddItemResult em vez de lançar uma exceção. 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 as runes do Svelte 5 ($state, $derived, $effect) para estado reativo, e a API de Context (setContext/getContext) para torná-lo disponível 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)
}

Decisões Principais de Design

Symbol('cart') como chave de context evita colisões caso outras bibliotecas também usem 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 mudanças 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) obtenha entradas separadas no carrinho.

4. Construir o Componente CartProvider

O CartProvider é um wrapper simples que chama createCartContext e renderiza seus filhos. O uso de 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 componente pai re-renderizasse e passasse novos valores de props, isso poderia disparar 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 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 Rota

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: inativo, 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 vinculação bidirecional com bind:value do componente pai, ao mesmo tempo que permite ao componente atualizar o valor internamente.

CartSummary

O componente de resumo do pedido com entrada de 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 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 í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 cartão flexível que usa 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 a substituição do Svelte 5 para slots. Eles permitem que 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 se o snippet não for 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. Conecte Layouts e Rotas

Layout Raiz

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

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 utiliza 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. Construa 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 descontos 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 nesta 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 carrinho 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 instâncias novas 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 provedor 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 chamam getCartContext() receberão o carrinho do fornecedor — não o carrinho 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 de índice do marketplace), lemos diretamente do localStorage, pois 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 possibilita 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 no carrinho local (adicionados enquanto estava desconectado) e itens no servidor (adicionados 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 utiliza uma estratégia de "servidor vence em conflitos, mantém adições locais":

Itens presentes no servidor e localmente: A versão do servidor prevalece (ela pode ter alterações de quantidade mais recentes de outro dispositivo)
Itens apenas no servidor: Mantidos (adicionados de outro dispositivo)
Itens apenas localmente: Mantidos (adicionados enquanto desconectado; o usuário espera que persistam)

Este é um bom padrão padrão porque preserva a intenção do usuário — tudo que ele adicionou 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 gera cinco requisições POST. O debounce de 1 segundo agrupa essas ações 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: Mutação de 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 cartão de listagem de produto de repente tem uma propriedade quantity. Um resultado de busca 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, os usuários podem adicionar mais itens do que você tem no inventário. Isso leva a falhas no cumprimento de pedidos, clientes insatisfeitos e custos com reembolsos. O padrão de objeto de resultado torna a falha explícita — o componente chamador 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 guarda isInitialized garante que carregamos primeiro e só então habilitamos o salvamento. Este é o bug de persistência mais comum em aplicações Svelte 5.

18. Considerações de Desempenho

Carrinhos de compras podem crescer bastante, e implementações mal otimizadas causam lag perceptí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-renderiza 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 de apenas uma informação.

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.

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

Carregamento Lazy do Drawer do Carrinho

Não renderize o drawer do carrinho até que ele 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 use 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 a 4 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 o desempenho endereçado, vamos recapitular os primitivos do Svelte 5 que tornaram essa arquitetura possível.

19. Recapitulação dos Padrões Principais 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 nas variáveis $state aciona atualizações na UI.

2. `$derived` — Valores Computados

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

Substitui as declarações reativas $:. 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. Ideal para persistência, logging ou manipulação do DOM.

5. `$effect.pre` — Efeitos de 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, composáveis e mais flexíveis do que os slots do Svelte 4.

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

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

Impede 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 praticamente 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 de "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 essa implementação poderosa é a interação entre as primitivas reativas 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 são recalculados 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 primitiva faz uma coisa bem feita e, juntas, criam um sistema onde as mudanças se propagam automaticamente das ações do usuário pelos cálculos até a interface 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 as 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 possam 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 permite padrões poderosos como o isolamento de carrinho com 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 exija.

Principais Aprendizados

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 com escopo e testabilidade. Stores globais vazam estado entre requisições e não podem ser limitadas a diferentes seções da sua aplicação.

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

Cálculos Derivados com $derived calculam totais, impostos e frete. Eles são recalculados 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 os itens ou descontos mudam. O effect 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 com Escopo através de providers aninhados permite marketplaces com múltiplos fornecedores, plataformas multi-tenant e qualquer arquitetura que exija instâncias de carrinho separadas com configurações diferentes.

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