Leyendo Contexto desde Ancestros

En el artículo anterior, aprendimos cómo proveer contexto — cómo transmitir datos desde un componente ancestro para que los descendientes puedan recibirlos. Ahora nos centramos en el otro lado de la ecuación: consumir contexto.

Proveer contexto es sencillo: llama a setContext con una clave y un valor, listo. Consumirlo tiene más matices. ¿Qué sucede cuando el contexto no existe? ¿Cómo manejas contexto opcional versus requerido? ¿Qué hay de la seguridad de tipos? Y existe una trampa sutil de reactividad con la desestructuración que toma a muchos desarrolladores por sorpresa.

No necesitas absorber todo en la primera lectura — enfócate en los patrones y revisita cuando lo necesites. Esta guía sirve tanto como recurso de aprendizaje como referencia a la que volverás.

Este artículo cubre todo lo que necesitas para consumir contexto con confianza:

Las tres funciones de consumidor: getContext, hasContext y getAllContexts
Manejo de contexto faltante: fail-fast, valores de respaldo y patrones defensivos
Construcción de utilidades reutilizables que estandarizan el acceso al contexto
Consumo con seguridad de tipos con createContext y helpers tipados
La trampa de la desestructuración que rompe la reactividad (y cómo evitarla)

La Función getContext

La función getContext es tu herramienta principal para recibir valores de contexto. Examinémosla a fondo.

Firma de la Función

function getContext<T>(key: any): T

La función toma un único parámetro, la clave que identifica qué contexto deseas, y retorna el valor del contexto. La clave debe coincidir exactamente con la que se usó en setContext.

Uso Básico

En su forma más simple:

<script>
	import { getContext } from 'svelte'

	const user = getContext('user')
</script>

<p>Welcome, {user.name}!</p>

Si un componente ancestro llamó a setContext('user', { name: 'Alice' }), entonces getContext('user') retorna { name: 'Alice' }.

El Proceso de Búsqueda

Cuando llamas a getContext(key), Svelte realiza una búsqueda que recorre el árbol de componentes hacia arriba:

Comienza en el padre del componente actual — El contexto se establece en los componentes, pero solo puedes acceder al contexto desde los ancestros, no desde ti mismo.
Verifica cada ancestro — Svelte comprueba si ese ancestro llamó a setContext(key, ...).
Retorna al primer resultado — Tan pronto como se encuentra un ancestro con esa clave, se retorna su valor.
Retorna undefined si no se encuentra — Si ningún ancestro estableció esa clave, el valor retornado es undefined y no es un error, así que ten cuidado.

Este proceso se visualiza a continuación:

App (setContext 'user' → Alice)    ← Step 4: Found! Return Alice
└── Layout                          ← Step 3: No 'user' context
    └── Dashboard                   ← Step 2: No 'user' context
        └── UserBadge               ← Step 1: getContext('user') called here
            Looking for 'user'...

IMPORTANTE: Esta búsqueda ocurre solo una vez durante la inicialización del componente — el contexto es estructural, no reactivo por diseño.

La Regla "El Más Cercano Gana"

Si múltiples ancestros establecen la misma clave, obtienes el valor del ancestro más cercano (el más inmediato):

RootLayout -> (setContext 'theme' → 'light')
└── Dashboard
    └── AdminPanel -> (setContext 'theme' → 'dark')
        └── Settings
            └── ThemeDisplay  ← getContext('theme') returns 'dark'

ThemeDisplay
↑ SettingsPanel      (no theme)
↑ DashboardLayout    ← FOUND: 'dark'
↑ RootLayout         (ignored)

El componente ThemeDisplay en la página Settings obtiene 'dark' porque AdminPanel está más cerca que RootLayout. Esto habilita poderosos patrones de sobreescritura donde los componentes internos pueden personalizar el contexto para su subárbol sin afectar el resto de la aplicación.

Lo que Retorna getContext

El valor de retorno es exactamente lo que se pasó a setContext. Sin transformación, sin copia, sin proxy — simplemente el mismo valor.

Para primitivos (cadenas, números, booleanos...), obtienes el valor tal como estaba en el momento en que se llamó a setContext:

<!-- Provider -->
<script>
	import { setContext } from 'svelte'
	let count = 5
	setContext('count', count)  // Stores 5
	count = 100  // Doesn't affect context
</script>

<!-- Consumer -->
<script>
	import { getContext } from 'svelte'
	const count = getContext('count')  // Gets 5, not 100
</script>

Para objetos (incluyendo arreglos, funciones, instancias de clases), obtienes una referencia al mismo objeto:

<!-- Provider -->
<script>
	import { setContext } from 'svelte'
	const user = { name: 'Alice', score: 0 }
	setContext('user', user)
	// Later...
	user.score = 100  // This IS visible to consumers
</script>

<!-- Consumer -->
<script>
	import { getContext } from 'svelte'
	const user = getContext('user')
	console.log(user.score)  // 100 (sees the modification)
</script>

Este compartir de referencias es la base de los patrones de contexto reactivo — pero requiere cuidado. Exploraremos esto en profundidad en el artículo Haciendo el Contexto Reactivo.

Contexto Faltante Retorna - undefined

Un comportamiento crítico: getContext no lanza un Error cuando no se encuentra la clave. Retorna silenciosamente undefined:

<script>
	import { getContext } from 'svelte'

	const user = getContext('user') // undefined if no ancestor set 'user'

	// This would crash!
	console.log(user.name) // TypeError: Cannot read property 'name' of undefined
</script>

Esto es lo que sucede cuando falta el contexto:

┌──────────────────────────────────────────────────────────────────┐
│ Component Initialization                                         │
│                                                                  │
│ const user = getContext('user')  // No provider found            │
│                    ↓                                             │
│           Returns undefined ⚠️  (No error thrown!)               │
│                    ↓                                             │
│ Execution continues normally...                                  │
└──────────────────────────────────────────────────────────────────┘
         │
         ↓ Later, when code tries to use it...
┌──────────────────────────────────────────────────────────────────┐
│ Event Handler / Effect / Render                                  │
│                                                                  │
│ function handleLogin() {                                         │
│   user.login(credentials)  ❌ TypeError: undefined.login         │
│ }                                                                │
│                                                                  │
│ <h1>{user.name}</h1>  ❌ TypeError: undefined.name               │
└──────────────────────────────────────────────────────────────────┘

Problem: Error occurs far from root cause!
         ↓

Three Prevention Strategies:

┌─────────────────────┐   ┌─────────────────────┐   ┌──────────────────────┐
│ 1. FAIL FAST        │   │ 2. FALLBACK         │   │ 3. NULLABLE          │
│                     │   │                     │   │                      │
│ if (!hasContext())  │   │ const user =        │   │ const user =         │
│   throw Error       │   │   hasContext()      │   │   hasContext()       │
│                     │   │   ? getContext()    │   │   ? getContext()     │
│ ✅ Detect at init   │   │   : defaultUser     │   │   : null             │
│ ✅ Clear message    │   │                     │   │                      │
│ ✅ Can't be ignored │   │ ✅ Always usable    │   │ if (user) {          │
│                     │   │ ✅ No crash         │   │   // Has context     │
│ Use: Required       │   │                     │   │ } else {             │
│      context        │   │ Use: Optional       │   │   // No context      │
│                     │   │      enhancement    │   │ }                    │
│                     │   │                     │   │                      │
│                     │   │                     │   │ ✅ Explicit check    │
│                     │   │                     │   │ ✅ Branch logic      │
│                     │   │                     │   │                      │
│                     │   │                     │   │ Use: Conditional     │
│                     │   │                     │   │      features        │
└─────────────────────┘   └─────────────────────┘   └──────────────────────┘

Este comportamiento es intencional — permite patrones de contexto opcional — pero requiere un manejo cuidadoso. La siguiente sección cubre cuándo y cómo usar cada estrategia.

La Restricción de Tiempo: Cuándo se Puede Llamar a getContext

Al igual que setContext, getContext debe llamarse durante la inicialización del componente — la ejecución sincrónica de tu bloque <script>.

Component Lifecycle Timeline
─────────────────────────────────────────────────────────────────────

Phase 1: INITIALIZATION                Phase 2: REACTIVE RUNTIME
┌─────────────────────────┐           ┌──────────────────────────┐
│ ✅ getContext ALLOWED   │           │ ❌ getContext FORBIDDEN  │
│                         │           │                          │
│ <script>                │           │ • Event handlers         │
│   const x = getContext()│           │ • $effect() callbacks    │
│                         │           │ • setTimeout/Promise     │
│   function setup() {    │           │ • After await            │
│     const y = getContext│           │                          │
│   }                     │           │ function onClick() {     │
│   setup() // ✅ Called  │           │   getContext() // ❌     │
│         immediately     │           │ }                        │
│ </script>               │           │                          │
│                         │           │ $effect(() => {          │
│ All synchronous code    │           │   getContext() // ❌     │
│ in <script> block runs  │           │ })                       │
└─────────────────────────┘           └──────────────────────────┘
         │                                       │
         │ Component mounted                     │ Reactive updates
         ↓                                       ↓
    [Context captured]                    [Use captured values]

Punto clave: Captura las referencias de contexto temprano y úsalas en todo momento. Si el valor del contexto contiene propiedades con $state, estas siguen siendo reactivas aunque la búsqueda en sí haya sido de una sola vez.

Ubicaciones Válidas

Los siguientes son lugares válidos para llamar a getContext:

<script>
	import { getContext } from 'svelte'

	// ✅ Top-level in script block
	const theme = getContext('theme')

	// ✅ Inside synchronous function called immediately
	function setupFromContext() {
		const config = getContext('config')
		return config.apiUrl
	}
	const apiUrl = setupFromContext() // Called during initialization

	// ✅ Inside IIFE (Immediately Invoked Function Expression)
	const user = (() => {
		return getContext('user')
	})()

	// ✅ Inside synchronous conditional
	let debug = false
	if (import.meta.env.DEV) {
		const devTools = getContext('devTools')
		debug = devTools?.enabled ?? false
	}
</script>

Ubicaciones Inválidas

No llames a getContext en estos lugares:

<script>
	import { getContext } from 'svelte'

	// ❌ Inside event handler
	function handleClick() {
		const user = getContext('user') // Error!
	}

	// ❌ Inside $effect
	$effect(() => {
		const theme = getContext('theme') // Error!
	})

	// ❌ Inside $derived (which runs reactively)
	// Note: $derived runs during initialization, but subsequent runs are reactive
	// This is a subtle edge case—generally avoid getContext in $derived

	// ❌ Inside setTimeout
	setTimeout(() => {
		const config = getContext('config') // Error!
	}, 0)

	// ❌ Inside Promise callbacks
	fetch('/api').then(() => {
		const api = getContext('api') // Error!
	})

	// ❌ After await (which makes the rest async)
	async function setup() {
		const data = await fetch('/api').then((r) => r.json())
		const config = getContext('config') // Error!
	}
	setup()
</script>

El Mensaje de Error

Si llamas a getContext fuera de la inicialización, Svelte lanza:

Error: `getContext(...)` can only be called during component initialization

Por Qué Existe Esta Restricción

Esta restricción refleja la que existe en setContext, y por razones relacionadas:

El contexto es estructural — Es parte de cómo se organiza el árbol de componentes, establecido en el momento del montaje.
Previsibilidad — Puedes confiar en que el contexto estará disponible (o no) desde el momento en que el componente se inicializa. No aparecerá ni desaparecerá de repente.
Rendimiento — Svelte no necesita rastrear el acceso al contexto de forma reactiva; es una búsqueda de una sola vez durante la inicialización.

La Solución: Capturar Durante la Inicialización

La solución es simple: captura los valores de contexto durante la inicialización y úsalos donde los necesites:

<script>
	import { getContext } from 'svelte'

	// Capture during initialization
	const auth = getContext('auth')
	const theme = getContext('theme')
	const toast = getContext('toast')

	// Now use freely in event handlers
	function handleLogin() {
		auth
			.login(credentials)
			.then(() => {
				toast.success('Welcome back!')
			})
			.catch((err) => {
				toast.error(err.message)
			})
	}

	// And in effects
	$effect(() => {
		document.body.setAttribute('data-theme', theme.current)
	})

	// And in derived values
	let greeting = $derived(`Hello, ${auth.user?.name ?? 'Guest'}!`)
</script>

<button onclick={handleLogin}>Login</button><p>{greeting}</p>

La referencia capturada permanece válida durante toda la vida útil del componente. Si el valor del contexto es un objeto con propiedades reactivas (usando $state), esas propiedades reactivas se actualizarán normalmente.

Verificar Contexto con hasContext

Antes de acceder al contexto, puede que quieras verificar si existe. La función hasContext hace exactamente esto.

Firma de la Función

function hasContext(key: any): boolean

Devuelve true si algún ancestro estableció esta clave de contexto, false en caso contrario.

Uso Básico

<script>
	import { getContext, hasContext } from 'svelte'

	// Check before accessing
	if (hasContext('user')) {
		const user = getContext('user')
		console.log('User:', user.name)
	} else {
		console.log('No user context available')
	}
</script>

Patrón Común: Verificar y Proveer un Valor por Defecto

<script>
	import { getContext, hasContext } from 'svelte'

	// Get context with fallback
	const theme = hasContext('theme')
		? getContext('theme')
		: { mode: 'light', accentColor: '#007bff' }
</script>

Este patrón es tan común que puede que quieras crear una función utilitaria (lo haremos más adelante).

Cuándo Usar hasContext

La decisión de verificar o no el contexto depende de tu caso de uso:

Escenario	Enfoque	Razonamiento
El contexto es requerido	No verificar; dejar que falle	Un contexto requerido faltante es un bug; fallar rápido y de forma clara
El contexto es opcional con un valor por defecto	Verificar con `hasContext`, proveer valor defecto	El componente debe funcionar de forma independiente
Comportamiento diferente con/sin contexto	Verificar y ramificar	Algunas funcionalidades solo están disponibles en ciertos contextos
Componente de librería/reutilizable	Generalmente verificar	Los componentes pueden usarse fuera de los proveedores esperados
Componente interno de la aplicación	Generalmente no verificar	Tú controlas el entorno

hasContext No Consume el Contexto

Un detalle importante: hasContext solo verifica la existencia—no recupera ni "consume" el contexto. Puedes llamarlo múltiples veces sin efectos secundarios:

<script>
	import { hasContext, getContext } from 'svelte'

	// These are independent checks
	const hasTheme = hasContext('theme')
	const hasUser = hasContext('user')
	const hasFeatureFlags = hasContext('features')

	// Now conditionally get what we need
	const theme = hasTheme ? getContext('theme') : defaultTheme
	const user = hasUser ? getContext('user') : null
</script>

Inspeccionar Todo el Contexto con getAllContexts

La función getAllContexts devuelve el mapa completo de contexto disponible en la posición actual del árbol.

Firma de la Función

function getAllContexts<T extends Map<any, any> = Map<any, any>>(): T

Devuelve un Map de JavaScript que contiene todos los pares clave-valor de contexto accesibles para este componente.

Uso Básico

<script>
	import { getAllContexts } from 'svelte'

	const allContexts = getAllContexts()

	console.log(allContexts)
	// Map(3) {
	//   'theme' => { mode: 'dark', ... },
	//   'user' => { name: 'Alice', ... },
	//   Symbol('auth') => { ... }
	// }

	// Use Map methods
	console.log(allContexts.has('theme')) // true
	console.log(allContexts.get('user')) // { name: 'Alice', ... }
	console.log(allContexts.size) // 3
</script>

1: Depuración

Cuando algo no funciona, es útil ver qué contexto está realmente disponible:

<script>
	import { getAllContexts } from 'svelte'

	// Development-only context inspection
	if (import.meta.env.DEV) {
		const ctx = getAllContexts()
		console.group('🔍 Available Context')
		for (const [key, value] of ctx) {
			console.log(`${String(key)}:`, value)
		}
		console.groupEnd()
	}
</script>

Puedes crear un componente de depuración reutilizable:

<!-- ContextDebugger.svelte -->
<script>
	import { getAllContexts } from 'svelte'

	let { show = false } = $props()

	const allContexts = getAllContexts()
	const entries = [...allContexts.entries()]
</script>

{#if show && import.meta.env.DEV}
	<details class="context-debugger">
		<summary>Context ({entries.length} keys)</summary>
		<ul>
			{#each entries as [key, value]}
				<li>
					<strong>{String(key)}</strong>
					<pre>{JSON.stringify(value, null, 2)}</pre>
				</li>
			{/each}
		</ul>
	</details>
{/if}

<style>
	.context-debugger {
		position: fixed;
		bottom: 1rem;
		right: 1rem;
		background: #1e1e1e;
		color: #d4d4d4;
		padding: 0.5rem;
		border-radius: 4px;
		font-size: 12px;
		max-width: 400px;
		max-height: 300px;
		overflow: auto;
		z-index: 9999;
	}

	pre {
		margin: 0;
		white-space: pre-wrap;
		word-break: break-all;
	}
</style>

2: Reenviar Contexto a Componentes Dinámicos

Cuando montas dinámicamente un componente fuera del árbol normal (por ejemplo, un modal renderizado en un portal), puede que quieras que herede el contexto actual:

<script>
	import { mount, getAllContexts } from 'svelte'
	import Modal from './Modal.svelte'

	// Capture context that should be forwarded
	const inheritedContext = getAllContexts()

	let modalInstance = null

	function openModal(content) {
		// Mount modal at document.body but with inherited context
		modalInstance = mount(Modal, {
			target: document.body,
			props: { content },
			context: inheritedContext // Forward context!
		})
	}

	function closeModal() {
		if (modalInstance) {
			modalInstance.$destroy()
			modalInstance = null
		}
	}
</script>

Sin reenviar el contexto, el modal no tendría ningún contexto (ya que document.body no tiene ningún ancestro de Svelte con contexto).

3: Crear Wrappers que Reenvían Contexto

A veces necesitas envolver un componente preservando todo su acceso al contexto:

<!-- ContextPreservingWrapper.svelte -->
<script>
	import { getAllContexts, setContext } from 'svelte'

	let { children, additionalContext = {} } = $props()

	// Get all inherited context
	const inherited = getAllContexts()

	// Re-provide everything from ancestors
	for (const [key, value] of inherited) {
		setContext(key, value)
	}

	// Add any additional context
	for (const [key, value] of Object.entries(additionalContext)) {
		setContext(key, value)
	}
</script>

<div class="wrapper">
	{@render children()}
</div>

Nota sobre el Timing

Al igual que las otras funciones de contexto, getAllContexts debe llamarse durante la inicialización del componente.

Manejar Contexto Faltante: Estrategias y Patrones

El contexto faltante es una de las fuentes más comunes de errores en tiempo de ejecución en arquitecturas basadas en contexto. Un componente espera que getContext('user') devuelva un objeto de usuario, pero en cambio obtiene undefined—y de repente estás depurando un críptico error "Cannot read property 'name' of undefined" tres componentes alejado del problema real.

La clave es que diferentes situaciones requieren diferentes estrategias. A veces el contexto faltante es un bug que debería fallar de forma ruidosa. Otras veces es esperado y tu componente debería degradarse con gracia. Exploremos cuándo usar cada enfoque.

Estrategia 1: Fallar Rápido para Contexto Requerido

Cuando el contexto es genuinamente requerido—es decir, tu componente no puede funcionar sin él—el mejor enfoque es fallar inmediatamente con un mensaje de error claro y accionable:

<script>
	import { getContext, hasContext } from 'svelte'

	if (!hasContext('auth')) {
		throw new Error(
			'AuthContext not found. ' +
				'Wrap this component in a layout that provides auth context. ' +
				'See: src/routes/+layout.svelte'
		)
	}

	const auth = getContext('auth')
</script>

¿Por qué fallar rápido?

Retroalimentación inmediata: Descubres el problema durante el desarrollo, no en producción cuando un usuario hace clic en un botón
Diagnóstico claro: El mensaje de error le dice a los desarrolladores exactamente qué está mal y dónde buscar
Previene fallos en cascada: Sin esta verificación, obtendrías un error confuso como TypeError: Cannot read property 'login' of undefined en algún lugar profundo de un manejador de eventos

Usa esta estrategia para contextos que son requisitos arquitectónicos—cosas como autenticación, enrutamiento o configuración a nivel de aplicación.

Estrategia 2: Fallback Elegante para Contexto Opcional

Algún contexto mejora un componente pero no es esencial. Un componente Button puede verse mejor cuando respeta el contexto del tema, pero de todas formas debería renderizar un botón perfectamente funcional sin él:

<script>
	import { getContext, hasContext } from 'svelte'

	let { children, onclick } = $props()

	// Theme is optional—component works without it
	const defaultTheme = {
		primaryColor: '#007bff',
		borderRadius: '4px'
	}

	const theme = hasContext('theme') ? getContext('theme') : defaultTheme
</script>

<button
	{onclick}
	style="
		background: {theme.primaryColor};
		border-radius: {theme.borderRadius};
	"
>
	{@render children()}
</button>

Este patrón hace que los componentes sean portables. Puedes usarlos en cualquier proyecto—ya sea que tenga tu sistema de temas o no—y simplemente funcionan.

Estrategia 3: Null Explícito para Funcionalidades Condicionales

A veces necesitas saber si el contexto fue provisto en lugar de usar un valor por defecto. Por ejemplo, puedes mostrar una interfaz diferente para usuarios autenticados versus usuarios anónimos:

<script>
	import { getContext, hasContext } from 'svelte'

	// Explicitly null when not available (not a default user object)
	const user = hasContext('user') ? getContext('user') : null
</script>

{#if user}
	<nav>
		<span>Welcome, {user.name}</span>
		<a href="/dashboard">Dashboard</a>
		<button onclick={() => auth.logout()}>Logout</button>
	</nav>
{:else}
	<nav>
		<a href="/login">Sign In</a>
		<a href="/register">Create Account</a>
	</nav>
{/if}

Usar null (en lugar de un usuario falso por defecto) hace que la distinción sea completamente clara en tu código.

Estrategia 4: Encadenamiento Opcional para Acceso Rápido

Para casos simples donde solo necesitas acceso seguro a propiedades, el encadenamiento opcional es conciso:

<script>
	import { getContext } from 'svelte'

	const user = getContext('user')
	const analytics = getContext('analytics')
</script>

<!-- Safe even if user is undefined -->
<p>Hello, {user?.name ?? 'Guest'}!</p>

<!-- Conditionally call methods -->
<button onclick={() => analytics?.track('button_clicked')}> Click me </button>

Esto funciona bien para componentes hoja que consumen contexto de manera pasiva. Sin embargo, evita abusar de él—si te encuentras escribiendo user?. en todas partes, considera usar la Estrategia 2 o 3 al comienzo de tu script.

Elegir la Estrategia Correcta

Escenario	Estrategia	Por qué
El componente no puede funcionar sin contexto	Falla Rápida	Detecta errores de configuración de inmediato
El contexto mejora pero no es obligatorio	Fallback Elegante	El componente sigue siendo portable
UI diferente para "tiene contexto" vs "no tiene"	Null Explícito	Lógica condicional clara
Acceso puntual a una propiedad	Encadenamiento Opcional	Conciso para casos simples
Librería/componente reutilizable	Fallback Elegante	Funciona en cualquier entorno
Componente interno de la app con proveedor garantizado	Falla Rápida	Documenta el requisito

Construir Utilidades de Contexto Reutilizables

Si te encuentras repitiendo los mismos patrones de manejo de contexto en muchos componentes, es momento de extraerlos en utilidades. Esto no solo reduce el código repetitivo, sino que también estandariza cómo tu equipo maneja el contexto en toda la aplicación.

Un Módulo de Utilidades Práctico

Aquí hay un conjunto de utilidades que cubren los patrones más comunes:

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

/**
 * Gets context or returns a fallback value.
 * Use for optional context with sensible defaults.
 *
 * @example
 * const theme = getContextOr('theme', { mode: 'light' })
 */
export function getContextOr<T>(key: any, fallback: T): T {
	return hasContext(key) ? getContext(key) : fallback
}

/**
 * Gets context or returns null.
 * Use when you need to distinguish "no context" from "has context".
 *
 * @example
 * const user = getContextOrNull('user')
 * if (user) { ... }
 */
export function getContextOrNull<T>(key: any): T | null {
	return hasContext(key) ? getContext(key) : null
}

/**
 * Gets context or throws a descriptive error.
 * Use for required context that must be provided by an ancestor.
 *
 * @example
 * const auth = requireContext('auth', 'Authentication')
 */
export function requireContext<T>(key: any, contextName: string): T {
	if (!hasContext(key)) {
		throw new Error(
			`${contextName} context is required but was not found. ` +
				`Ensure this component is rendered within a provider that sets '${String(key)}' context.`
		)
	}
	return getContext(key)
}

Usar las Utilidades

Con estas utilidades, tus componentes se vuelven más limpios y consistentes:

<script>
	import { requireContext, getContextOr, getContextOrNull } from '$lib/context/utils'

	// Required: throws descriptive error if missing
	const auth = requireContext('auth', 'Authentication')

	// Optional with default: always returns a usable value
	const theme = getContextOr('theme', { mode: 'light', accent: '#007bff' })

	// Optional nullable: returns null if missing
	const analytics = getContextOrNull('analytics')

	function trackClick() {
		// Only track if analytics is available
		analytics?.track('button_clicked')
	}
</script>

Crear Accesores de Contexto Tipados

Para una experiencia de desarrollo aún mejor, crea accesores tipados para cada contexto en tu aplicación:

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

export interface AuthContext {
	readonly user: User | null
	readonly isAuthenticated: boolean
	login(credentials: Credentials): Promise<void>
	logout(): Promise<void>
}

const AUTH_KEY = Symbol('auth')

export function setAuthContext(value: AuthContext) {
	return setContext(AUTH_KEY, value)
}

export function getAuthContext(): AuthContext {
	if (!hasContext(AUTH_KEY)) {
		throw new Error(
			'Auth context not found. ' +
				'Ensure this component is rendered within src/routes/+layout.svelte'
		)
	}
	return getContext(AUTH_KEY)
}

export function getAuthContextOrNull(): AuthContext | null {
	return hasContext(AUTH_KEY) ? getContext(AUTH_KEY) : null
}

Ahora consumir el contexto de autenticación está completamente tipado y es autodocumentado:

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

	const auth = getAuthContext()

	// Full TypeScript support
	auth.user?.name // ✅ string | undefined
	auth.isAuthenticated // ✅ boolean
	auth.login(creds) // ✅ Promise<void>
</script>

Este patrón escala bien—crea un archivo por dominio de contexto (auth.ts, theme.ts, toast.ts) y tu equipo siempre sabrá exactamente cómo proveer y consumir cada contexto.

Consumo con Seguridad de Tipos

La integración con TypeScript hace que consumir contexto sea más seguro y ergonómico.

Aserciones de Tipo Básicas

Con getContext sin procesar, necesitas asertar tipos:

<script lang="ts">
	import { getContext } from 'svelte'

	interface User {
		id: string
		name: string
		email: string
	}

	// Type assertion needed
	const user = getContext('user') as User

	// Or with generic
	const user2 = getContext<User>('user')
</script>

Esto funciona pero tiene desventajas:

La aserción podría ser incorrecta (sin verificación en tiempo de ejecución)
Necesitas importar/definir el tipo en cada lugar donde lo consumes

Usar `createContext` (Recomendado)

Con createContext (Svelte 5.40+), los tipos se infieren automáticamente:

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

export interface User {
	id: string
	name: string
	email: string
	role: 'admin' | 'user' | 'guest'
}

export const [getUser, setUser] = createContext<User>()

<!-- Consumer.svelte -->
<script lang="ts">
	import { getUser } from '$lib/context/user'

	// Fully typed! No assertion needed.
	const user = getUser()

	// TypeScript knows everything
	user.name // ✅ string
	user.email // ✅ string
	user.role // ✅ 'admin' | 'user' | 'guest'
	user.foo // ❌ Property 'foo' does not exist
</script>

`createContext` Lanza Error si Falta

A diferencia de getContext, el getter de createContext lanza un error cuando falta el contexto:

<script>
	import { getUser } from '$lib/context/user'

	// If no ancestor called setUser(), this throws immediately:
	// "Context was not provided"
	const user = getUser()
</script>

Esto es una característica, no un error—detecta problemas de configuración durante el desarrollo en lugar de causar misteriosos errores de undefined más adelante.

`createContext` con Valores por Defecto

Puedes proporcionar un valor por defecto que se usa cuando ningún proveedor establece el contexto:

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

interface Config {
	apiUrl: string
	timeout: number
	debug: boolean
}

export const [getConfig, setConfig] = createContext<Config>({
	apiUrl: '/api',
	timeout: 5000,
	debug: false
})

Ahora getConfig() devuelve el valor por defecto si ningún ancestro proporcionó la configuración, en lugar de lanzar un error.

Consumir Múltiples Contextos

Los componentes del mundo real a menudo necesitan datos de varios contextos—configuración de tema, información del usuario, feature flags, notificaciones toast. Exploremos patrones para gestionar esto de manera limpia.

Enfoque Directo: Múltiples Llamadas a getContext

El enfoque directo funciona bien para la mayoría de los componentes:

<script>
	import { getContext } from 'svelte'

	const theme = getContext('theme')
	const user = getContext('user')
	const locale = getContext('locale')
	const toast = getContext('toast')
</script>

Esto es explícito, fácil de entender y funciona perfectamente para componentes que necesitan un puñado de contextos. No lo sobrediseñes.

Hook Consolidado para Conjuntos de Contextos Comunes

Si muchos componentes necesitan la misma combinación de contextos, extrae un hook:

// src/lib/hooks/useAppContext.ts
import { getContext, hasContext } from 'svelte'

export function useAppContext() {
	return {
		user: getContext('user'),
		theme: hasContext('theme') ? getContext('theme') : { mode: 'light' },
		locale: getContext('locale'),
		toast: getContext('toast')
	}
}

<script>
	import { useAppContext } from '$lib/hooks/useAppContext'

	const { user, theme, locale, toast } = useAppContext()
</script>

Recuerda: Esta función debe llamarse durante la inicialización del componente—no puedes llamarla dentro de un manejador de eventos.

Hooks por Dominio (Recomendado para Aplicaciones Grandes)

En lugar de un hook monolítico, crea hooks enfocados para cada dominio:

// src/lib/hooks/useAuth.ts
import { requireContext } from '$lib/context/utils'

export function useAuth() {
	return requireContext('auth', 'Authentication')
}

// src/lib/hooks/useTheme.ts
import { getContextOr } from '$lib/context/utils'

const defaultTheme = { mode: 'light', accent: '#007bff' }

export function useTheme() {
	return getContextOr('theme', defaultTheme)
}

// src/lib/hooks/usePermissions.ts
import { getContextOr } from '$lib/context/utils'

export function usePermissions() {
	const permissions = getContextOr('permissions', [])

	return {
		list: permissions,
		has: (perm: string) => permissions.includes(perm),
		hasAll: (...perms: string[]) => perms.every((p) => permissions.includes(p)),
		hasAny: (...perms: string[]) => perms.some((p) => permissions.includes(p))
	}
}

El uso es limpio y autodocumentado:

<script>
	import { useAuth } from '$lib/hooks/useAuth'
	import { useTheme } from '$lib/hooks/useTheme'
	import { usePermissions } from '$lib/hooks/usePermissions'

	const auth = useAuth()
	const theme = useTheme()
	const { has: hasPermission } = usePermissions()
</script>

{#if hasPermission('admin')}
	<AdminPanel />
{/if}

Este patrón escala bien porque cada hook:

Encapsula su propio manejo de errores
Provee valores predeterminados sensatos
Puede agregar propiedades computadas (como hasPermission)
Es independientemente testeable

La Trampa de la Desestructuración: Un Problema Común de Reactividad

Hay un problema sutil pero importante al trabajar con contexto reactivo que hace tropezar a muchos desarrolladores. Entenderlo te ahorrará horas de depuración.

El Problema: Reactividad Perdida

Considera este código que parece inofensivo:

<script>
	import { getContext } from 'svelte'

	const settings = getContext('settings')
	// settings = { theme: 'light', fontSize: 16, language: 'en' }

	// Destructuring seems convenient...
	const { theme, fontSize, language } = settings
</script>

<div class={theme}>
	<p style="font-size: {fontSize}px">Language: {language}</p>
</div>

Ahora imagina que el proveedor actualiza settings.theme a 'dark'. Tu componente no se actualizará. Seguirá mostrando 'light'.

Por Qué Ocurre Esto

Cuando desestructuras, JavaScript extrae los valores en ese momento y los asigna a nuevas variables:

const { theme } = settings
// Is equivalent to:
const theme = settings.theme // Copies 'light' into a new variable

La variable theme ahora contiene la cadena 'light' de forma independiente. No existe una conexión continua con themeSettings.theme. Cuando el proveedor cambia themeSettings.theme a 'dark', tu variable theme no se ve afectada—sigue siendo 'light'.

Solución 1: Acceder a las Propiedades Directamente (La Más Simple)

La solución más fácil es omitir la desestructuración y acceder a las propiedades directamente en el objeto:

<script>
	import { getContext } from 'svelte'

	const settings = getContext('settings')
</script>

<!-- Access properties directly—this WILL update -->
<div class={settings.theme}>
	<p style="font-size: {settings.fontSize}px">
		Language: {settings.language}
	</p>
</div>

Cada vez que Svelte renderiza, lee el valor actual de settings.theme. Si el proveedor lo cambió, verás el nuevo valor.

Solución 2: Desestructuración Reactiva con `$derived`

Si quieres la comodidad de nombres de variables cortos, usa $derived para crear enlaces reactivos:

<script>
	import { getContext } from 'svelte'

	const settings = getContext('settings')

	// These re-evaluate whenever settings changes
	let theme = $derived(settings.theme)
	let fontSize = $derived(settings.fontSize)
	let language = $derived(settings.language)
</script>

<!-- Now these update automatically -->
<div class={theme}>
	<p style="font-size: {fontSize}px">Language: {language}</p>
</div>

Cada $derived crea un enlace reactivo que se vuelve a calcular cada vez que sus dependencias cambian.

Solución 3: Desestructuración a Nivel de Plantilla con `{@const}`

Para un uso puntual en un bloque de plantilla específico, puedes desestructurar justo donde lo necesites:

<script>
	import { getContext } from 'svelte'

	const settings = getContext('settings')
</script>

{@const { theme, fontSize, language } = settings}
<div class={theme}>
	<p style="font-size: {fontSize}px">Language: {language}</p>
</div>

La declaración {@const} se ejecuta en cada renderizado, por lo que siempre captura los valores actuales. Esto es útil cuando necesitas desestructurar dentro de un bucle o bloque condicional.

¿Cuándo Importa Esto?

Esta trampa solo te afecta cuando:

El valor del contexto es reactivo (contiene $state internamente)
Desestructuras valores primitivos (cadenas, números, booleanos)
El proveedor realmente cambia esos valores

Si tu contexto es una configuración de solo lectura que nunca cambia, la desestructuración está perfectamente bien. Pero ante la duda, accede a las propiedades directamente—siempre es seguro.

Exploraremos los patrones de reactividad con mucha mayor profundidad en el artículo Making Context Reactive.

Juntando Todo: Un Ejemplo del Mundo Real

Apliquemos todo lo que hemos aprendido para construir un componente Card que demuestre patrones robustos de consumo de contexto.

Los Requisitos

Nuestro componente Card debería:

Adaptarse al contexto de tema cuando esté disponible
Funcionar de forma independiente con valores predeterminados sensatos (portabilidad)
Soportar variantes que deriven colores del tema
Estar completamente tipado para una gran experiencia de desarrollo

La Implementación

<!-- src/lib/components/Card.svelte -->
<script lang="ts">
	import { getContext, hasContext } from 'svelte'

	// --- Props ---
	interface Props {
		title?: string
		subtitle?: string
		variant?: 'default' | 'primary' | 'muted'
		children: import('svelte').Snippet
	}

	let { title, subtitle, variant = 'default', children }: Props = $props()

	// --- Theme Context (optional with fallback) ---
	interface Theme {
		mode: 'light' | 'dark'
		colors: {
			primary: string
			background: string
			text: string
			muted: string
			border: string
		}
		borderRadius: string
		shadow: string
	}

	const defaultTheme: Theme = {
		mode: 'light',
		colors: {
			primary: '#007bff',
			background: '#ffffff',
			text: '#1a1a1a',
			muted: '#f5f5f5',
			border: '#e0e0e0'
		},
		borderRadius: '8px',
		shadow: '0 2px 8px rgba(0, 0, 0, 0.1)'
	}

	// Strategy 2: Graceful fallback for optional context
	const theme: Theme = hasContext('theme') ? getContext('theme') : defaultTheme

	// --- Derived Styling ---
	// Use $derived to react to theme changes
	let backgroundColor = $derived(
		{
			default: theme.colors.background,
			primary: theme.colors.primary,
			muted: theme.colors.muted
		}[variant]
	)

	let textColor = $derived(variant === 'primary' ? '#ffffff' : theme.colors.text)
</script>

<article
	class="card"
	class:dark={theme.mode === 'dark'}
	style="
		--card-bg: {backgroundColor};
		--card-text: {textColor};
		--card-border: {theme.colors.border};
		--card-radius: {theme.borderRadius};
		--card-shadow: {theme.shadow};
	"
>
	{#if title}
		<header class="card-header">
			<h3 class="card-title">{title}</h3>
			{#if subtitle}
				<p class="card-subtitle">{subtitle}</p>
			{/if}
		</header>
	{/if}

	<div class="card-body">
		{@render children()}
	</div>
</article>

<style>
	.card {
		background: var(--card-bg);
		color: var(--card-text);
		border: 1px solid var(--card-border);
		border-radius: var(--card-radius);
		box-shadow: var(--card-shadow);
		overflow: hidden;
	}

	.card.dark {
		border-color: rgba(255, 255, 255, 0.1);
	}

	.card-header {
		padding: 1rem 1.5rem;
		border-bottom: 1px solid var(--card-border);
	}

	.card-title {
		margin: 0;
		font-size: 1.25rem;
		font-weight: 600;
	}

	.card-subtitle {
		margin: 0.25rem 0 0;
		opacity: 0.7;
		font-size: 0.875rem;
	}

	.card-body {
		padding: 1.5rem;
	}
</style>

Qué Hace Esto Robusto

Funciona en cualquier lugar: El tema predeterminado asegura que la tarjeta se renderice correctamente incluso sin un proveedor de tema
Se adapta cuando existe el contexto: Cuando se usa dentro de un layout con tema, automáticamente toma los colores y estilos de la aplicación
Reactivo a los cambios: Usar $derived para los colores de variantes significa que la tarjeta se actualiza si el tema cambia entre modo claro/oscuro
Completamente tipado: TypeScript detecta incompatibilidades entre las estructuras de tema esperadas y proporcionadas
Propiedades CSS personalizadas: El puente entre el script y los estilos mantiene el componente mantenible

Ejemplos de Uso

<!-- Works standalone -->
<div class="grid">
	<!-- Works standalone -->
	<Card title="Hello World">
		<p>This card uses default styling.</p>
	</Card>

	<!-- Adapts to theme context -->
	<Card title="Themed Card" variant="primary">
		<p>This card uses your app's primary color.</p>
	</Card>

	<!-- Inside a dark-themed section -->
	<Card title="Dark Mode" subtitle="Automatically adapts">
		<p>Border and shadow adjust for dark backgrounds.</p>
	</Card>
</div>

<style>
	.grid {
		display: grid;
		gap: 1.5rem;
		grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
		margin-top: 2rem;
	}
</style>

Conclusión

Consumir contexto es la contraparte de proveerlo, y entender ambos lados completa tu modelo mental de cómo fluyen los datos a través del árbol de componentes de Svelte. Mientras que proveer contexto consiste en transmitir disponibilidad, consumir contexto consiste en acceder a esa disponibilidad de manera confiable y segura.

Los patrones en este artículo—desde llamadas básicas a getContext hasta utilidades tipadas sofisticadas—todos abordan el mismo desafío fundamental: ¿cómo accedes a datos que pueden o no existir, de una manera que sea type-safe, mantenible y depurable? La respuesta depende de tu caso de uso: falla rápido para contexto requerido, valores de retroceso elegantes para contexto opcional, y comprobaciones explícitas de nulo cuando necesitas distinguir entre los dos.

La trampa de la desestructuración merece especial énfasis porque sorprende a tantos desarrolladores. El modelo mental a recordar es simple: los primitivos se copian, las referencias se comparten. Cuando desestructuras un primitivo de un objeto de contexto reactivo, obtienes una instantánea que nunca se actualiza. Cuando accedes a él a través del objeto (context.theme en lugar de solo theme), obtienes el valor actual en todo momento.

Con tanto el proveer como el consumir contexto dominados, estás equipado para construir aplicaciones donde los datos fluyan limpiamente a través de tu árbol de componentes—sin prop drilling, sin acoplamiento a través de intermediarios, solo declaraciones claras de qué está disponible y qué se necesita.

Puntos Clave

Consumir contexto de manera efectiva se reduce a entender algunos principios clave:

Las Funciones Principales

getContext(key) recupera el contexto del ancestro más cercano. Devuelve undefined si no se encuentra—no un error.
hasContext(key) verifica la existencia sin recuperar. Úsala para patrones de contexto opcional.
getAllContexts() devuelve todo como un Map. Excelente para depuración y reenvío de contexto.

La Regla de Tiempo

Todas las funciones de contexto deben ejecutarse durante la inicialización del componente. Captura lo que necesites en la parte superior de tu script, luego usa esos valores en cualquier lugar.

Manejo de Contexto Faltante

Situación	Estrategia
El componente no puede funcionar sin él	Falla rápido con un error descriptivo
Mejora opcional	Provee un valor predeterminado sensato
Necesita distinguir "faltante" de "presente"	Devuelve null explícito
Acceso puntual rápido	Encadenamiento opcional (`context?.value`)

La Trampa de la Desestructuración

La desestructuración rompe la reactividad para los valores primitivos. O accede a las propiedades directamente en el objeto de contexto, o usa $derived para crear enlaces reactivos.

Seguridad de Tipos

Usa createContext (Svelte 5.40+) para tipado automático y comportamiento de error al faltar, o crea funciones utilitarias tipadas para estandarizar el acceso al contexto en toda tu aplicación.

Con estos patrones dominados, consumirás contexto de manera segura y efectiva en todas tus aplicaciones Svelte.

Qué Sigue

Explora cómo se comporta el contexto en jerarquías de componentes complejas en Context Scope and Flow, donde dominarás la regla "el más cercano gana" y los patrones de anulación de contexto.

Ver También

Documentación Oficial

getContext API — Referencia de API
hasContext API — Referencia de API
getAllContexts API — Referencia de API

Leyendo Contexto desde Ancestros

La Función getContext

Firma de la Función

Uso Básico

El Proceso de Búsqueda

La Regla "El Más Cercano Gana"

Lo que Retorna getContext

Contexto Faltante Retorna - undefined

La Restricción de Tiempo: Cuándo se Puede Llamar a getContext

Ubicaciones Válidas

Ubicaciones Inválidas

El Mensaje de Error

Por Qué Existe Esta Restricción

La Solución: Capturar Durante la Inicialización

Verificar Contexto con hasContext

Firma de la Función

Uso Básico

Patrón Común: Verificar y Proveer un Valor por Defecto

Cuándo Usar hasContext

hasContext No Consume el Contexto

Inspeccionar Todo el Contexto con getAllContexts

Firma de la Función

Uso Básico

1: Depuración

2: Reenviar Contexto a Componentes Dinámicos

3: Crear Wrappers que Reenvían Contexto

Nota sobre el Timing

Manejar Contexto Faltante: Estrategias y Patrones

Estrategia 1: Fallar Rápido para Contexto Requerido

Estrategia 2: Fallback Elegante para Contexto Opcional

Estrategia 3: Null Explícito para Funcionalidades Condicionales

Estrategia 4: Encadenamiento Opcional para Acceso Rápido

Elegir la Estrategia Correcta

Construir Utilidades de Contexto Reutilizables

Un Módulo de Utilidades Práctico

Usar las Utilidades

Crear Accesores de Contexto Tipados

Consumo con Seguridad de Tipos

Aserciones de Tipo Básicas

Usar createContext (Recomendado)

createContext Lanza Error si Falta

createContext con Valores por Defecto

Consumir Múltiples Contextos

Enfoque Directo: Múltiples Llamadas a getContext

Hook Consolidado para Conjuntos de Contextos Comunes

Hooks por Dominio (Recomendado para Aplicaciones Grandes)

La Trampa de la Desestructuración: Un Problema Común de Reactividad

El Problema: Reactividad Perdida

Por Qué Ocurre Esto

Solución 1: Acceder a las Propiedades Directamente (La Más Simple)

Solución 2: Desestructuración Reactiva con $derived

Solución 3: Desestructuración a Nivel de Plantilla con {@const}

¿Cuándo Importa Esto?

Juntando Todo: Un Ejemplo del Mundo Real

Los Requisitos

La Implementación

Qué Hace Esto Robusto

Ejemplos de Uso

Conclusión

Puntos Clave

Qué Sigue

Ver También

Documentación Oficial

Artículos Relacionados

Usar `createContext` (Recomendado)

`createContext` Lanza Error si Falta

`createContext` con Valores por Defecto

Solución 2: Desestructuración Reactiva con `$derived`

Solución 3: Desestructuración a Nivel de Plantilla con `{@const}`