De la Mecánica al Dominio

A lo largo de esta serie, hemos explorado la mecánica de la API de Contexto de Svelte—cómo proveer contexto, consumirlo, manejar anidamiento profundo, hacerlo reactivo con runes y aplicarlo en escenarios del mundo real como gestión de temas y compartición de datos complejos. Ahora entiendes cómo funciona el contexto.

Este artículo cambia el enfoque hacia cómo usar el contexto correctamente. Estableceremos patrones profesionales que hacen que tu código de contexto sea mantenible, testeable y escalable. No son preferencias de estilo arbitrarias—son lecciones aprendidas al construir y mantener grandes aplicaciones Svelte donde el contexto juega un rol arquitectónico central.

Al seguir estas prácticas, escribirás código de contexto que:

Es inmediatamente comprensible para otros desarrolladores
Detecta errores en tiempo de compilación en lugar de en tiempo de ejecución
Puede ser probado de forma aislada
Tiene buen rendimiento incluso en aplicaciones complejas
Escala de manera fluida a medida que tu aplicación crece

Ya sea que seas un principiante buscando establecer buenos hábitos desde el inicio, o un desarrollador experimentado buscando refinar tus patrones, esta guía proporciona la base para un uso profesional del contexto.

El Marco de Decisión

Antes de adentrarnos en los detalles de implementación, necesitas un modelo mental para decidir cuándo usar contexto versus otros patrones. Este marco de decisión te salvará del error común de sobrediseñar problemas simples o subdiseñar los complejos.

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

Este marco encapsula la idea central: el contexto ocupa un nicho específico—estado compartido con alcance de subárbol—y sobresale cuando se usa de manera apropiada. No es un reemplazo para props, stores o funciones de carga, sino un complemento de ellos.

Convenciones de Nomenclatura

La nomenclatura consistente hace el código predecible. Cuando los desarrolladores pueden adivinar correctamente los nombres de funciones y variables, pasan menos tiempo leyendo documentación y buscando en el código base. Esta sección establece los patrones de nomenclatura que siguen los códigos base profesionales de Svelte.

Nomenclatura de Claves de Contexto

Si usas claves de tipo string, adopta un patrón de nomenclatura consistente en toda tu aplicación:

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

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

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

Para aplicaciones en producción, prefiere Symbols o createContext para eliminar por completo los riesgos de colisión. Las claves de tipo string funcionan bien para aplicaciones pequeñas, pero las claves Symbol garantizan unicidad—dos Symbols nunca son iguales, incluso con la misma descripción:

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

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

Estabilidad de Claves de Contexto

Las claves de contexto deben ser estables durante toda la vida útil de tu aplicación. Cambiar las claves rompe a los consumidores, a veces de forma silenciosa. Considera este patrón problemático:

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

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

En su lugar, centraliza las claves y ocúltalas detrás de funciones de acceso:

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

O mejor aún, proporciona funciones de acceso tipadas que oculten la clave por completo:

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

const KEY = Symbol('theme')

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

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

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

Ahora los consumidores nunca tocan la clave directamente, y puedes cambiar la implementación sin romper a nadie:

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

	const theme = getThemeContext()
</script>

Este patrón oculta la implementación de la clave, proporciona seguridad de tipos, permite cambios de clave sin romper a los consumidores y documenta el tipo de retorno esperado.

Patrones de Nomenclatura para Funciones

Establece una nomenclatura consistente para las funciones relacionadas con el contexto y mantenla en todo tu código base:

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

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

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

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

Elige un patrón y mantén la consistencia. Mezclar getAuthContext con useCart genera fricción cognitiva y hace que tu código base sea más difícil de navegar.

Patrones de Nomenclatura para Archivos

Nombra los archivos para reflejar su contenido e indicar si usan runes:

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

Usa la extensión .svelte.ts cuando el archivo use runes ($state, $derived, $effect). Esto no es solo una convención—Svelte lo requiere para el procesamiento de runes. Equivocarse en esto produce errores crípticos que hacen perder tiempo de depuración.

Nomenclatura de Componentes Proveedores

Los componentes proveedores deben indicar claramente qué proveen:

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

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

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

Nombres de Tipos

Sigue las convenciones de TypeScript para la nomenclatura de tipos:

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

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

Organización de Archivos

La forma en que organizas los archivos de contexto afecta la facilidad de descubrimiento y el mantenimiento. La elección correcta depende del tamaño de tu aplicación, la estructura del equipo y cómo se relacionan tus contextos con las funcionalidades.

Patrón 1: Directorio de Contexto Centralizado

Todo el contexto en un solo lugar:

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

Este patrón ofrece varias ventajas. Todos los contextos son fáciles de encontrar en un solo lugar, y las importaciones se vuelven simples y consistentes. Obtienes una visión clara del estado global de la aplicación, siendo adecuado para aplicaciones pequeñas a medianas donde los contextos son verdaderamente compartidos entre funcionalidades.

El archivo index.ts exporta todo lo que los consumidores necesitan:

// lib/context/index.ts

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

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

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

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

Patrón 2: Contexto Coubicado con la Funcionalidad

El contexto vive junto a su funcionalidad:

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

Este patrón mantiene el contexto cerca de sus consumidores, haciendo que las funcionalidades sean autocontenidas y portables. Los límites claros de propiedad surgen de forma natural. Escala bien para aplicaciones y equipos grandes, y facilita entender de un vistazo qué necesita una funcionalidad.

Cada funcionalidad expone una API pública limpia a través de su index.ts:

// lib/features/auth/index.ts

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

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

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

Patrón 3: Enfoque Híbrido

Contexto central/compartido centralizado, contexto específico de funcionalidad coubicado:

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

Usa esta guía de decisiones para elegir la ubicación correcta:

Tipo de contexto	Ubicación	Razonamiento
Tema, locale, feature flags	Centralizado	Usado en toda la aplicación
Auth	Cualquiera	Depende de qué tan específicos sean tus componentes de auth
Carrito de compras	Feature	La lógica del carrito es específica del feature
Asistente de checkout	Feature	Solo se usa en el flujo de checkout
Gestores de modal/toast	Centralizado	Usado desde muchos features

Seguridad de tipos

TypeScript transforma el contexto de un misterio en tiempo de ejecución a un contrato en tiempo de compilación. Invierte en un tipado adecuado—eso genera dividendos en la experiencia del desarrollador y en la prevención de bugs todos los días.

Define interfaces explícitas

Nunca dependas de la inferencia de tipos para las APIs de contexto. Las interfaces explícitas sirven como documentación, habilitan un mejor soporte del IDE y detectan errores tempranamente:

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

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

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

La versión con interfaz explícita le indica a los desarrolladores exactamente con qué están trabajando antes de que lean la implementación.

Usa `createContext` para acceso con seguridad de tipos

Svelte 5.40+ provee createContext para seguridad de tipos automática:

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

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

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

Los consumidores obtienen IntelliSense completo sin ningún esfuerzo adicional:

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

	const auth = getAuth()

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

Funciones wrapper tipadas

Si no usas createContext, crea funciones wrapper tipadas que provean los mismos beneficios:

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

const AUTH_KEY = Symbol('auth')

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

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

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

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

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

	return setContext(AUTH_KEY, context)
}

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

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

Utilidades de contexto genéricas

Crea utilidades reutilizables para patrones comunes para reducir el código repetitivo:

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

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

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

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

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

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

El uso se vuelve limpio y consistente:

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

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

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

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

Principios de diseño de API

Una API de contexto bien diseñada facilita la vida de los consumidores y previene el uso incorrecto. Estos principios aplican tanto si estás construyendo contexto para tu propia aplicación como para una librería compartida.

Expone getters, no estado en crudo

Siempre usa getters para exponer el estado. Esto proporciona encapsulación, garantiza que los consumidores reciban valores reactivos frescos y permite la refactorización futura:

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

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

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

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

Los getters garantizan valores frescos, permiten refactorizaciones futuras sin romper a los consumidores y habilitan la validación o transformación antes de retornar los valores.

Provee acciones, no solo estado

Las buenas APIs incluyen tanto el estado como las operaciones que lo modifican. No hagas que los consumidores tengan que descubrir cómo actualizar el estado correctamente:

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

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

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

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

Incluye estados de carga y error

Las operaciones asíncronas deben exponer su estado. Los consumidores no deberían tener que rastrear los estados de carga y error por sí mismos:

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

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

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

	// Initial load
	load()

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

Usa tipos Result para operaciones que pueden fallar

Para operaciones que pueden fallar, retorna objetos result en lugar de lanzar excepciones. Esto hace que el manejo de errores sea explícito y componible:

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

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

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

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

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

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

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

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

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

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

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

Los consumidores manejan los resultados explícitamente, haciendo visibles los casos de error:

<script>
	const cart = getCartContext()

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

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

Mantén las APIs mínimas y estables

Empieza con poco. Siempre puedes agregar a una API de contexto, pero eliminar es un cambio disruptivo:

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

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

Consideraciones de rendimiento

El contexto está diseñado para ser eficiente, pero los patrones de uso inadecuado aún pueden causar problemas. Entender estos patrones te ayuda a evitar problemas de rendimiento antes de que se conviertan en un problema real.

Mide antes de optimizar

Las búsquedas de contexto son rápidas—típicamente microsegundos. Antes de aplicar patrones de optimización, verifica que realmente tengas un problema de rendimiento:

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

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

La mayoría de las aplicaciones nunca necesitan optimizaciones específicas del contexto. Los patrones a continuación abordan casos extremos—aplícalos solo cuando el profiling revele el contexto como un verdadero cuello de botella, no como optimización prematura.

Evita actualizaciones frecuentes del contexto

Las búsquedas de contexto ocurren una sola vez durante la inicialización del componente. Sin embargo, si el valor de tu contexto cambia con frecuencia y muchos componentes lo leen, podrías ver impactos en el rendimiento:

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

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

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

Si muchos componentes consumen este contexto, cada uno reaccionará a cada movimiento del mouse. La solución es throttlear las actualizaciones o dividir el contexto:

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

	let { children } = $props()

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

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

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

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

{@render children()}

El rune $effect generalmente no debería asignar estado—para eso está $derived. Sin embargo, los manejadores de eventos externos (eventos del DOM, timers, mensajes de WebSocket) son excepciones legítimas. Estos eventos se originan fuera del sistema de reactividad de Svelte y deben insertar valores en el estado.

El ejemplo de rastreo del mouse de arriba es válido porque:

Los movimientos del mouse son eventos externos del DOM, no derivados de otro estado
No hay forma de expresar "posición actual del mouse" como un valor $derived
El efecto limpia correctamente su event listener

Cuando veas que $effect asigna estado, pregúntate: "¿Está respondiendo a algo externo?" Si es sí, es apropiado. Si el valor podría calcularse a partir de otro estado reactivo, usa $derived en su lugar.

Dividir Contextos Grandes

Si tienes un objeto de contexto grande donde diferentes componentes necesitan diferentes partes, considera dividirlo:

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

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

Usar `$derived` para Valores Computados

Calcula los valores derivados una sola vez en el proveedor, no repetidamente en los consumidores:

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

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

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

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

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

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

Inicialización Diferida

Para operaciones costosas, inicializa de forma diferida:

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

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

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

Pruebas de Contexto

Un contexto bien diseñado es un contexto testeable. Los patrones en esta sección garantizan que la lógica de tu contexto pueda probarse de forma aislada y que los componentes que consumen contexto puedan probarse de manera efectiva.

Probar la Lógica de Contexto de Forma Aislada

Extrae la lógica de contexto en archivos .svelte.ts para poder probarla sin renderizar componentes:

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

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

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

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

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

		reset() {
			value = initial
		}
	}
}

Prueba la lógica directamente:

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

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

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

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

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

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

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

Probar Componentes Proveedor

Prueba los proveedores renderizándolos con consumidores de prueba:

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

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

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

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

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

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

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

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

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

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

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

	const counter = getCounterContext()
</script>

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

Simular Contexto para Pruebas Unitarias

A veces quieres probar un componente con un contexto simulado en lugar del proveedor real:

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

const AUTH_KEY = Symbol('auth')

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

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

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

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

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

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

{@render children()}

Crear un Wrapper de Prueba Genérico

Para probar múltiples contextos a la vez:

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

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

	const props: Props = $props()

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

{@render props.children()}

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

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

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

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

Prácticas de Documentación

Una buena documentación hace que el contexto sea utilizable por desarrolladores que no lo escribieron, incluyendo a ti mismo en el futuro.

Comentarios JSDoc

Documenta todas las funciones e interfaces públicas con ejemplos:

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

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

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

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

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

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

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

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

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

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

README para Directorios de Contexto

En aplicaciones más grandes, incluye un README en tu directorio de contexto que documente los contextos disponibles, sus proveedores, consumidores y requisitos de composición. Esto se convierte en el punto de entrada para los desarrolladores que son nuevos en tu base de código.

Anti-Patrones Comunes

Entender qué no hacer es tan importante como conocer las buenas prácticas. Estos anti-patrones son trampas comunes que desperdician tiempo de desarrollo y generan dolores de cabeza de mantenimiento.

1: Contexto para Cada Prop

No uses contexto solo para evitar escribir prop={value}. Las props son explícitas y se documentan por sí solas:

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

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

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

2: Contextos Monolíticos Enormes

No pongas todo en un solo contexto. Divide por funcionalidad/dominio:

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

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

3: Anidamiento Excesivo de Proveedores

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

Consolida en un único proveedor compuesto:

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

4: Contexto para Comunicación entre Componentes Hermanos

El contexto fluye hacia abajo, no de forma lateral. Para la comunicación entre componentes hermanos, eleva el estado a su ancestro común.

5: Recrear Objetos de Contexto en Cada Renderizado

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

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

6: Contexto para Configuración Estática

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

Usa variables de entorno o constantes en su lugar:

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

7: Contexto para Estilos

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

Las propiedades personalizadas de CSS manejan mejor los estilos:

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

Cuándo NO Usar Context

El contexto es poderoso pero no es apropiado en todos los casos. Saber cuándo evitarlo es tan importante como saber cuándo usarlo.

Usa Props Cuando...

Las props son la opción correcta para la comunicación directa entre padre e hijo, cuando la API del componente debe ser explícita, o cuando querés el máximo soporte de TypeScript:

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

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

Usa Stores Cuando...

Los stores son mejores cuando el estado es verdaderamente global (singleton), necesita persistir a través del desmontaje de componentes, o cuando código fuera de componentes necesita acceso:

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

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

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

Usa las Funciones Load de SvelteKit Cuando...

Las funciones load son la opción correcta cuando los datos provienen del servidor, diferentes rutas necesitan datos diferentes, o cuando necesitás obtención de datos segura para SSR:

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

Matriz de Referencia Rápida

Necesidad	Solución
Pasar datos un nivel hacia abajo	Props
Pasar datos a través de 3+ niveles	Context
Estado interno de librería de componentes	Context
Singleton a nivel de aplicación	Store
Datos del servidor específicos de ruta	SvelteKit load
Datos que sobreviven a los componentes	Store
Estado compartido con alcance en subárbol	Context
Necesitar valores diferentes por subárbol	Context
Acceso desde código fuera de componentes	Store

Conclusión

Las buenas prácticas no son restricciones—son patrones que emergen de resolver los mismos problemas repetidamente. Las convenciones en este artículo representan sabiduría acumulada de construir y mantener aplicaciones donde el contexto juega un rol arquitectónico central.

La inversión en convenciones de nomenclatura da frutos cada vez que un desarrollador (incluyendo el vos del futuro) puede adivinar el nombre de una función correctamente sin buscar en el código. La inversión en seguridad de tipos da frutos cada vez que TypeScript detecta un error en tiempo de compilación en lugar de en producción. La inversión en testabilidad da frutos cuando podés refactorizar la lógica de contexto con confianza sabiendo que tus tests detectarán las regresiones.

Quizás lo más importante es que saber cuándo no usar contexto previene el error común de recurrir a una herramienta poderosa cuando una más simple sería suficiente. Las props siguen siendo la opción correcta para la comunicación directa entre padre e hijo. Los stores siguen siendo la opción correcta para el estado verdaderamente global. Las funciones load siguen siendo la opción correcta para los datos del servidor. El contexto ocupa un nicho específico—estado compartido con alcance en subárbol—y sobresale cuando se usa apropiadamente.

Aplicá estos patrones de manera consistente, y tu arquitectura basada en contexto será una base sobre la que podés construir con confianza, no una fuente de confusión y errores.

Puntos Clave

Estas prácticas transforman el contexto de una característica simple a una herramienta profesional:

Comenzá con el marco de decisión — Usá props para relaciones directas, contexto para estado compartido con alcance en subárbol, stores para singletons globales, y funciones load para datos del servidor.
Las convenciones de nomenclatura importan — Usá patrones consistentes para las claves (user-auth), funciones (createAuthContext, getAuthContext), archivos (auth.svelte.ts), y componentes (AuthProvider.svelte).
Mantené las claves estables — Centralizá las claves y ocultálas detrás de funciones de acceso para permitir cambios sin romper a los consumidores.
Tipá todo explícitamente — Definí interfaces, usá createContext o wrappers con tipos, y nunca dependas de la inferencia de tipos para APIs públicas.
Diseñá APIs mínimas y orientadas a acciones — Exponé getters (no el estado sin procesar), proporcioná acciones junto con el estado, incluí estados de carga/error, y usá tipos de resultado para operaciones que pueden fallar.
Optimizá de manera reflexiva — Aplicá throttle a las actualizaciones frecuentes, dividí contextos grandes, calculá valores derivados en los providers, e inicializá recursos costosos de manera lazy.
Testeá en múltiples niveles — Extraé la lógica a archivos .svelte.ts para tests unitarios, creá componentes wrapper de prueba para tests de integración, y mockeá el contexto al testear consumidores.
Evitá los anti-patrones comunes — No uses contexto para padre-hijo directo, no crees contextos monolíticos, no hagas provider soup, no uses contexto para configuración estática o estilos.

Aplicá estas prácticas de manera consistente, y tu arquitectura basada en contexto será un placer con el que trabajar—mantenible, testeable y escalable.

Qué Sigue

Aprendé qué puede salir mal y cómo solucionarlo en Problemas y Depuración de Context, que cubre errores comunes, técnicas de depuración y trampas que atrапan incluso a desarrolladores experimentados.

Ver También

Documentación Oficial

Svelte Context — Guía oficial
Svelte Testing — Patrones de testing
Archivos .svelte.ts — Runes en TypeScript