Por Qué los Carritos de Compras Son Difíciles

Un carrito de compras pone a prueba la gestión de estado: muchas páginas lo leen y escriben, los totales deben mantenerse reactivos, y la persistencia debe ser confiable. Context te da un modelo limpio y escalable, pero solo si evitas la trampa del store global ingenuo que rompe el aislamiento de SSR, el scope multi-tenant y la confiabilidad en los tests.

En este artículo, construirás un carrito listo para producción con variantes, totales reactivos, persistencia, validación de descuentos y aislamiento por scope; luego lo extenderás con patrones de sincronización con el servidor y rendimiento usando $state, $derived y $effect.

¿Por Qué Context para Carritos?

Los carritos de compras parecen un caso perfecto para el estado global. Todas las páginas necesitan acceso, ¿verdad? Pero la experiencia enseña: el estado global del carrito crea más problemas de los que resuelve.

Considera estos escenarios reales:

Plataformas marketplace: Múltiples vendedores, cada uno con su propio flujo de pago
E-commerce multi-sitio: Una app sirve varios storefronts
Portales B2B: Diferentes departamentos con presupuestos separados
Wishlist vs carrito: Diferentes "bolsas" con comportamiento similar
Renderizado en servidor: El aislamiento de requests es obligatorio

Context te da un estado de carrito aislado y con scope que escala a estas complejidades. Construyámoslo correctamente.

El Problema con los Stores Globales

Antes de profundizar en context, entendamos por qué el estado global, una opción aparentemente natural para algo tan universal como un carrito de compras, crea problemas significativos en aplicaciones de producción.

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.                │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

Context resuelve los tres problemas gracias a su diseño fundamental:

Seguridad en SSR: Cada request del servidor crea un árbol de componentes nuevo con sus propias instancias de contexto. El estado no puede filtrarse entre requests porque cada uno obtiene un contexto aislado.

Aislamiento por Scope: El contexto fluye hacia abajo a través del árbol de componentes. Diferentes secciones de tu app pueden tener contextos de carrito completamente distintos al anidar providers con diferentes configuraciones.

Independencia en Tests: Cada test puede renderizar su propio árbol de componentes con su propio contexto de carrito. Sin estado compartido no hay contaminación entre tests.

Patrones de Carrito en la Práctica

El patrón de carrito más común usado en Marketplace es el carrito unificado. ¿Por qué? Es un modelo mental más simple que simplifica la experiencia del usuario y el procesamiento backend al consolidar todos los ítems en un único carrito. Es el predeterminado para la mayoría de los sitios y plataformas de e-commerce como Shopify, Magento y WooCommerce.

Sin embargo, para esta demo se eligió intencionalmente el ejemplo de carrito por vendedor para mostrar el aislamiento de contexto por scope. En esta demo, la app tiene un contexto de carrito global, y las rutas de vendedor lo sobreescriben con un contexto específico del vendedor. Los providers anidados sobreescriben los contextos padre, por lo que cada subárbol de vendedor obtiene su propia instancia de carrito mientras el resto de la app mantiene el carrito 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

Puedes ver este patrón en acción en plataformas como DoorDash, Uber Eats e Instacart, donde cada restaurante o tienda tiene su propio carrito y flujo de pago, requisitos de pedido mínimo, procesamiento de pagos, etc.

Cuándo tiene sentido:

Delivery de comida: No puedes pedir de McDonald's y Burger King en una sola entrega
Cumplimiento diferente: Cada vendedor envía por separado con logística incompatible
Distintos procesadores de pago: Cada vendedor gestiona sus propios pagos
Mayoreo B2B: Diferentes términos, contratos y pedidos mínimos por proveedor
Storefronts white-label: Cada vendedor es esencialmente su propia tienda con marca propia

Resumen de la Arquitectura del Carrito

Un sistema de carrito bien arquitecturado separa las responsabilidades de forma clara. Así es como encajan las piezas:

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   │   │  │  │
│  │  │  └─────────────┘  └─────────────┘  └─────────────┘   │  │  │
│  │  └──────────────────────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

La arquitectura sigue un flujo de datos claro: $state contiene la fuente de verdad, $derived calcula todos los valores secundarios, $effect maneja los efectos secundarios como la persistencia, y la API de context expone tanto el estado como las acciones a los componentes consumidores.

Planificación del Sistema de Carrito

Antes de escribir código, definamos qué necesita manejar un carrito de compras de producción. Pensar en los requisitos de antemano lleva a un mejor diseño de API.

Requisitos Principales

Categoría	Operaciones	Descripción
Gestión de Ítems	Agregar, actualizar, eliminar	Manejar productos con variantes (talla, color)
Control de Cantidad	Incrementar, decrementar, fijar	Respetar límites de stock, validar rangos
Cálculos	Subtotal, impuesto, envío, total	Recálculo reactivo y automático
Descuentos	Aplicar, validar, eliminar	Códigos promocionales validados en el servidor
Persistencia	Guardar, cargar, sincronizar	Sobrevivir recargas de página, sincronizar opcionalmente con el servidor
Consultas	Verificar contenido, obtener cantidades	Búsquedas eficientes para el estado de la UI

Decisiones de Modelado de Datos

Varias decisiones afectan cómo modelamos los datos del carrito:

Identidad del Ítem: El ID de un producto por sí solo no es suficiente cuando el mismo producto tiene variantes. Una camiseta azul en talla Large es una línea de carrito diferente a la misma camiseta en talla Medium. Generamos identificadores compuestos a partir del ID del producto más las opciones de variante.

Almacenamiento de Precios: Guardar los precios en centavos como enteros evita problemas de precisión de punto flotante. Un precio de $19.99 se convierte en 1999 centavos. Todos los cálculos usan enteros, y solo formateamos a moneda para la visualización.

Límites de Stock: El carrito aplica los límites de maxQuantity. Agregar ítems más allá del stock disponible falla de forma controlada con un resultado de error tipado.

Cálculos: Todos los valores derivados, subtotales, impuestos y envío, se calculan mediante $derived. Cada componente ve valores consistentes y sincronizados automáticamente.

Objetos de Resultado: Las operaciones del carrito devuelven objetos de resultado tipados en lugar de lanzar errores. Esto hace que el manejo de errores sea explícito y con tipos seguros.

Qué Vas a Construir

En este tutorial, construirás una aplicación de carrito de compras completa usando la Context API y las runes de Svelte 5. El proyecto abarca gestión de estado reactivo, persistencia en localStorage, aislamiento de carrito multi-vendedor, un sistema de wishlist y códigos de descuento validados en el servidor, todo sin ninguna librería externa de gestión de estado.

Un carrito de compras con operaciones de agregar/eliminar/actualizar, límites de cantidad y totales por línea
Un sistema de wishlist que funciona junto al carrito
Un marketplace multi-vendedor donde cada vendedor tiene un carrito aislado con su propia moneda, tasa de impuesto y reglas de envío
Un sistema de códigos de descuento con validación del lado del servidor
Estado persistente usando localStorage con guardado/carga automático mediante $effect
Componentes de UI reutilizables con snippets de Svelte 5 y $props()

Prerrequisitos

Node.js 18+
Conocimiento básico de Svelte y TypeScript
Familiaridad con el enrutamiento de SvelteKit

1. Configuración del Proyecto

Crea un nuevo proyecto SvelteKit e instala las dependencias:

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

Elige la plantilla de TypeScript cuando se te solicite. Tu package.json debe 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"
	}
}

Estructura del Proyecto

Esta es la estructura de archivos que construiremos:

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 los Tipos

Comienza definiendo las interfaces de TypeScript que describen el modelo de datos de tu carrito. Cada valor monetario se almacena en centavos para evitar problemas de punto flotante.

Crea 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 Qué Objetos de Resultado en Lugar de Excepciones?

Observa que addItem devuelve AddItemResult en lugar de lanzar una excepción. Este patrón le da a los consumidores control explícito sobre el manejo de errores sin try/catch, y hace que los posibles modos de fallo sean visibles en el sistema de tipos.

3. Crear el Contexto del Carrito

Este es el núcleo de la aplicación. El contexto del carrito usa las runes de Svelte 5 ($state, $derived, $effect) para el estado reactivo, y la Context API (setContext/getContext) para hacerlo disponible en todo el árbol de componentes.

Crea 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)
}

Decisiones Clave de Diseño

Symbol('cart') como clave de contexto previene colisiones si otras librerías también usan context.
Las propiedades getter en el objeto de contexto (get items()) aseguran que los consumidores siempre lean el valor reactivo más reciente.
$effect.pre carga los datos persistidos antes del primer renderizado para evitar un destello de contenido vacío.
$effect para el guardado automático se ejecuta cada vez que items o appliedDiscount cambian — no se necesitan llamadas manuales de guardado.
SvelteDate se usa en lugar de Date porque el sistema de reactividad de Svelte 5 puede rastrear cambios en instancias de SvelteDate.
generateItemId crea un ID determinístico a partir del ID del producto más las opciones ordenadas, de modo que el mismo producto con variantes diferentes (p. ej., size:M vs size:L) obtiene entradas separadas en el carrito.

4. Construir el Componente CartProvider

El CartProvider es un wrapper delgado que llama a createCartContext y renderiza sus hijos. Usar untrack asegura que el contexto se cree solo una vez con los valores iniciales de las props.

Crea 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 Qué `untrack`?

Sin untrack, el sistema de reactividad de Svelte rastrearía las props dentro del callback. Si un padre se volviera a renderizar y pasara nuevos valores de props, podría disparar la creación del contexto nuevamente. untrack captura los valores iniciales e ignora los cambios posteriores — el contexto se crea exactamente una vez.

5. Crear el Contexto de Wishlist

La wishlist es más simple que el carrito — solo rastrea productos sin cantidades. Sigue el mismo patrón de la Context API.

Crea 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
}

Crea 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. Construir el Componente WishlistProvider

Crea 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. Datos de Productos y Utilidades

Constantes de Rutas

Crea 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

Formato de Precios

Crea 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)
}

Datos de Productos y Vendedores

Crea 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 del Carrito

AddToCartButton

Este botón proporciona retroalimentación visual a través de múltiples estados: inactivo, agregando, agregado y error.

Crea 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

Un ícono de encabezado con una insignia que muestra la cantidad total.

Crea 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

Un control +/- reutilizable con validación de entrada y limitación de valores.

Crea 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>

Nota el uso de $bindable — esto habilita el enlace bidireccional con bind:value desde el componente padre, al mismo tiempo que permite que el componente actualice el valor internamente.

CartSummary

El componente de resumen del pedido con entrada de código de descuento.

Crea 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 estilos: Cada componente anterior incluye bloques <style> con alcance definido. Por brevedad en este artículo, se omite parte del CSS. Consulta el código fuente completo para ver los estilos en su totalidad.

9. Componentes de UI de Lista de Deseos

WishlistButton

Un botón de alternancia con un ícono de corazón.

Crea 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

Crea 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 Compartidos

ProductCard

Un componente de tarjeta flexible que utiliza snippets de Svelte 5 para slots personalizables.

Crea 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>

Explicación de los Snippets

Los snippets son el reemplazo de Svelte 5 para los slots. Permiten que los componentes padres pasen contenido renderizable a los hijos:

<!-- 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>

El hijo los renderiza con {@render image?.()} — el ?.() asegura que no genere un error si el snippet no fue proporcionado.

Crea src/lib/components/Header.svelte:

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

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

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

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

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

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

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

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

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

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

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

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

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

11. Conectar Layouts y Rutas

Layout Raíz

El layout raíz envuelve toda la aplicación con ambos proveedores.

Crear 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

La sección de demo usa un reset de layout (+layout@.svelte) para salir del layout raíz y proveer su propio contexto aislado con un encabezado.

Crear 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>

El sufijo @ en el nombre del archivo le indica a SvelteKit que reinicie la cadena de layout — esta página y sus hijos no heredarán el layout raíz.

12. Construir las Páginas

Página de Productos

Crear 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 del Carrito

Crear 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 Deseos

Crear 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 Descuento

Crear un endpoint de API de SvelteKit para la validación de descuentos del lado del servidor.

Crear 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-Vendedor

El marketplace demuestra el patrón más poderoso de esta aplicación: proveedores de contexto anidados. Cada página de vendedor envuelve su contenido en un nuevo CartProvider con configuración específica del vendedor, aislando completamente su carrito del global.

Carga del Servidor para el Layout del Vendedor

Crear 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 del Vendedor (Contexto Anidado)

Aquí es donde ocurre la magia. El layout del vendedor crea instancias nuevas de CartProvider y WishlistProvider con claves de almacenamiento y configuración específicas del vendedor. Estas anulan los contextos del padre para todos los componentes hijos.

Crear 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>

Cómo Funciona el Aislamiento de Contexto

Cuando se anidan componentes CartProvider, el proveedor interno crea un contexto nuevo usando la misma clave Symbol('cart'). La API de contexto de Svelte usa el ancestro más cercano, por lo que todos los componentes hijos que llamen a getCartContext() recibirán el carrito del vendedor — no el 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

Los datos de cada vendedor persisten de forma independiente en localStorage bajo claves como vendor-1-cart, vendor-2-cart, etc.

Utilidad de Resumen de Carritos por Vendedor

Para mostrar un resumen entre vendedores (por ejemplo, en el índice del marketplace), leemos directamente desde localStorage ya que los contextos de vendedor no están montados en esa página.

Crear 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. Sincronización del Carrito del Lado del Servidor

Para usuarios con sesión iniciada, querrás sincronizar el carrito con tu backend. Esto permite la persistencia del carrito entre dispositivos y la recuperación de carritos abandonados.

El desafío principal es manejar la fusión cuando un usuario inicia sesión. Puede que tenga artículos en su carrito local (agregados sin haber iniciado sesión) y artículos en el servidor (agregados desde otro dispositivo). Necesitas una estrategia para reconciliar estas dos fuentes.

Crear una fábrica de contexto de carrito mejorada que agregue capacidades de sincronización con el 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 Qué Esta Estrategia de Fusión?

La función de fusión anterior usa una estrategia de "el servidor gana en conflictos, conservar adiciones locales":

Artículos en servidor y local: Gana la versión del servidor (puede tener cambios de cantidad más recientes desde otro dispositivo)
Artículos solo en el servidor: Se conservan (agregados desde otro dispositivo)
Artículos solo en local: Se conservan (agregados sin haber iniciado sesión, el usuario espera que persistan)

Este es un buen valor predeterminado porque preserva la intención del usuario — todo lo que agregaron localmente se mantiene, y los cambios remotos son respetados. Para uso en producción, probablemente agregarías marcas de tiempo a cada artículo y usarías "el último en escribir gana" para los conflictos, o le pedirías al usuario que resuelva las diferencias.

¿Por Qué Usar Debounce?

Sin debounce, cada cambio individual de cantidad dispararía una solicitud de red. Si un usuario hace clic en el botón "+" cinco veces rápidamente, eso son cinco solicitudes POST. El debounce de 1 segundo agrupa estas en una sola solicitud, reduciendo la carga del servidor y evitando condiciones de carrera donde una solicitud más antigua llega después de una más reciente.

17. Errores Comunes y Anti-Patrones

Error 1: Usar Solo el ID del Producto como ID del Artículo del Carrito

// 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 qué importa: En cualquier tienda con variantes, el mismo producto en diferentes tallas o colores debe ser una línea separada en el carrito. El usuario espera que "Camiseta Azul (L)" y "Camiseta Azul (M)" se rastreen de forma independiente. Usar solo el ID del producto las fusiona en una sola línea, perdiendo silenciosamente la información de la variante.

Error 2: Mutar Objetos de Producto

// 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 qué importa: Si mutás el objeto producto, cada componente que tiene una referencia a ese producto verá la mutación. Una tarjeta de listado de productos de repente tiene una propiedad quantity. Un resultado de búsqueda ahora tiene addedAt. Esto crea bugs difíciles de rastrear donde partes no relacionadas de la UI se comportan de manera inesperada.

Error 3: Seguimiento Manual del 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 qué importa: El seguimiento manual crea bugs de sincronización. Cada operación que cambia los ítems también debe actualizar el total, y es fácil olvidarse de alguna. Con $derived, el total siempre se calcula a partir de la fuente de verdad (el array de ítems). No hay manera de que se desincronice.

Error 4: Ignorar los Límites de Stock

// 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 qué importa: Sin validación de stock, los usuarios pueden agregar más ítems de los que tenés en inventario. Esto lleva a fallas en el cumplimiento, clientes enojados y costos de reembolso. El patrón de objeto de resultado hace que la falla sea explícita — el componente que lo llama debe manejar la posibilidad de que el agregado haya fallado.

Error 5: Sobreescribir el Almacenamiento Antes de Cargar

// 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 qué importa: El $effect para guardar se ejecuta en cuanto el componente se monta. Si todavía no cargaste los datos persistidos, guarda el estado vacío por defecto, eliminando permanentemente el carrito del usuario. El guard isInitialized asegura que carguemos primero y luego habilitemos el guardado. Este es el bug de persistencia más común en las aplicaciones Svelte 5.

18. Consideraciones de Rendimiento

Los carritos de compras pueden crecer mucho, y las implementaciones mal optimizadas causan lag notorio en la UI. Aquí hay estrategias para mantener tu carrito rápido.

Minimizar Re-renderizados con Valores Derivados Separados

Estructurá tus valores derivados como cómputos independientes en lugar de un ú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 qué importa: Cuando los valores $derived son separados, la reactividad de grano fino de Svelte significa que un componente que solo lee itemCount no se volverá a renderizar cuando cambie shipping. Con un único objeto de resumen, cada consumidor se re-renderiza en cada cambio porque la referencia del objeto cambia.

En nuestra implementación, sí exponemos un objeto summary por conveniencia, pero los valores derivados individuales (itemCount, totalQuantity, isEmpty) también están disponibles para los componentes que solo necesitan un dato.

Debounce de Persistencia

No guardes en localStorage en cada pulsación de tecla en los inputs de cantidad:

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 qué importa: localStorage.setItem es sincrónico y bloquea el hilo principal. Para un carrito con muchos ítems, serializar a JSON y escribir puede tomar varios milisegundos. Si el usuario cambia cantidades rápidamente, esto se acumula. Un debounce de 300ms agrupa los cambios rápidos en una única escritura.

Nota: Nuestra implementación actual guarda de forma sincrónica (sin debounce) por simplicidad. Para carritos con 50+ ítems, agregar debounce vale la pena.

Carga Lazy del Drawer del Carrito

No renderices el drawer del carrito hasta que se abra:

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

Por qué importa: El drawer del carrito frecuentemente incluye componentes complejos (selectores de cantidad, formularios de descuento, cálculos de resumen). Renderizarlo en segundo plano desperdicia memoria y ciclos de CPU. Los bloques {#if} de Svelte desmontan completamente el contenido cuando es false, por lo que los componentes no existen hasta que se los necesita.

Usar Bloques Each con Clave

Siempre usá clave en tus bloques {#each} cuando renderices ítems del carrito:

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

Por qué importa: Sin una clave, Svelte usa diffing basado en índices. Cuando eliminás el segundo ítem de una lista de cinco, Svelte cree que los ítems 2-4 cambiaron todos (porque sus índices se desplazaron). Con una clave, Svelte sabe exactamente qué nodo del DOM eliminar. Esto importa especialmente durante animaciones o cuando los ítems tienen estado interno.

Con el rendimiento resuelto, recapitulemos los primitivos de Svelte 5 que hicieron posible esta arquitectura.

19. Resumen de Patrones Clave de Svelte 5

1. `$state` — Variables Reactivas

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

Reemplaza las declaraciones reactivas let de Svelte 4. Cualquier mutación a las variables $state dispara actualizaciones en la UI.

2. `$derived` — Valores Computados

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

Reemplaza las sentencias reactivas $:. Recomputa automáticamente cuando cambian las dependencias.

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

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))
})

Usá .by() cuando la derivación necesita más que una única expresión.

4. `$effect` — Efectos Secundarios

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

Se ejecuta cada vez que sus dependencias rastreadas cambian. Ideal para persistencia, registro o manipulación del DOM.

5. `$effect.pre` — Efectos de Pre-renderizado

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

Se ejecuta antes de las actualizaciones del DOM. Se usa aquí para cargar datos persistidos antes del primer pintado.

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

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

$props() declara las props del componente. $bindable habilita el enlace bidireccional con bind:value.

7. API de Contexto con Símbolos

const CART_KEY = Symbol('cart')

// In provider
setContext(CART_KEY, context)

// In consumer
getContext(CART_KEY)

Los Símbolos previenen colisiones de claves. getContext devuelve el valor del ancestro más cercano que llamó a setContext con la misma clave.

8. Propiedades Getter para Contexto Reactivo

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

Los getters aseguran que los consumidores siempre lean el valor reactivo actual en lugar de una instantánea desactualizada.

9. Snippets (Reemplaza los Slots)

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

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

Los snippets son tipados, componibles y más flexibles que los slots de Svelte 4.

10. `untrack` — Prevenir el Rastreo de Dependencias

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

Previene el rastreo reactivo dentro del callback. Se usa para asegurar que el contexto se cree una sola vez con los valores iniciales.

Conclusión

El carrito de compras ejemplifica cómo el contexto transforma la gestión de estado compleja en algo manejable e intuitivo. Un carrito toca casi todas las partes de una aplicación de comercio electrónico: las páginas de producto necesitan agregar artículos, los encabezados necesitan mostrar conteos, las tarjetas de producto necesitan indicadores de "en el carrito", y los flujos de pago necesitan el contenido completo del carrito. Sin contexto, tendrías que pasar los datos del carrito y las funciones de actualización a través de docenas de componentes intermedios. Con contexto, cualquier componente en cualquier lugar simplemente llama a getCartContext() y obtiene todo lo que necesita.

Lo que hace poderosa esta implementación es la interacción entre los primitivos reactivos de Svelte 5. La runa $state mantiene el arreglo de artículos, haciéndolo reactivo. La runa $derived calcula totales, impuestos, envío y descuentos — valores que se recalculan automáticamente cuando los artículos cambian y se mantienen consistentes en todos los componentes. La runa $effect maneja la persistencia, guardando en localStorage cada vez que el carrito cambia sin requerir llamadas explícitas de guardado. Cada primitivo hace una cosa bien, y juntos crean un sistema donde los cambios se propagan automáticamente desde las acciones del usuario a través de los cálculos hasta la interfaz de usuario y el almacenamiento.

Los objetos de resultado para las operaciones merecen especial atención. En lugar de lanzar errores o devolver simples booleanos, métodos como addItem devuelven resultados estructurados con códigos de error específicos. Esto hace que el manejo de errores sea explícito — los llamadores deben reconocer que las operaciones pueden fallar — y con seguridad de tipos — TypeScript garantiza que todos los casos de error sean manejados. El mismo patrón aplica a cualquier contexto con operaciones que pueden fallar: errores de validación, fallos de API, o violaciones de reglas de negocio se benefician de resultados explícitos y tipados.

La naturaleza jerárquica del contexto habilita patrones poderosos como el aislamiento de carritos con ámbito. Un marketplace puede tener carritos completamente separados para cada vendedor, cada uno con su propia clave de almacenamiento, moneda y configuración de impuestos. Los componentes no saben en qué carrito están — simplemente llaman a getCartContext() y obtienen el más cercano. Este mismo patrón se extiende a múltiples tipos de carrito (lista de deseos, listas de comparación), sincronización con el servidor, y cualquier otra variación que tu aplicación requiera.

Conclusiones Clave

Construir un carrito de compras con contexto demuestra cómo el sistema de reactividad de Svelte 5 crea una gestión de estado elegante y mantenible:

Contexto sobre Stores Globales: El contexto proporciona seguridad para SSR, aislamiento de solicitudes, estado con ámbito y capacidad de prueba. Los stores globales filtran estado entre solicitudes y no pueden delimitar el ámbito a diferentes secciones de tu aplicación.

Estado Reactivo con $state mantiene los artículos del carrito y el descuento. Cuando estos cambian, todo lo que depende de ellos se actualiza automáticamente — no se requiere sincronización manual.

Cálculos Derivados con $derived computan totales, impuestos y envío. Estos se recalculan solo cuando sus dependencias cambian, y cada componente ve los mismos valores consistentes.

Persistencia Automática con $effect guarda el carrito en localStorage cada vez que los artículos o descuentos cambian. El efecto rastrea sus propias dependencias y se ejecuta cuando es necesario.

Objetos de Resultado para Operaciones hacen que el manejo de errores sea explícito y con seguridad de tipos. Los límites de stock, errores de validación y otros fallos devuelven resultados estructurados que los llamadores deben manejar.

Aislamiento con Ámbito a través de proveedores anidados habilita marketplaces con múltiples vendedores, plataformas multi-tenant, y cualquier arquitectura que requiera instancias de carrito separadas con diferentes configuraciones.

Aplica estos mismos principios a cualquier estado complejo que necesites compartir a lo largo de tu aplicación. La combinación de primitivos reactivos y contexto crea sistemas que son tanto poderosos como mantenibles.