Manejo Avanzado de Errores y Aislamiento de Componentes

En el mundo de las aplicaciones web modernas, los errores no son excepciones que deban temerse, sino realidades inevitables que deben gestionarse con elegancia. Un fallo visible para el usuario, un rechazo de promesa no manejado o un componente que no logra renderizarse pueden transformar una aplicación pulida en una experiencia frustrante. Svelte 5 introduce el elemento especial <svelte:boundary> como respuesta a este desafío: un mecanismo declarativo y componible para aislar fallos y mantener la estabilidad de la aplicación incluso cuando componentes individuales encuentran problemas.

Esta guía explora el elemento <svelte:boundary> con profundidad integral, examinando no solo su sintaxis y propiedades, sino el pensamiento arquitectónico detrás del manejo efectivo de errores en aplicaciones basadas en componentes. Ya sea que estés construyendo dashboards complejos orientados a datos, herramientas colaborativas en tiempo real o productos de cara al consumidor donde la confiabilidad es primordial, comprender los límites de error cambiará fundamentalmente la forma en que abordes la resiliencia en tus aplicaciones Svelte.

Comprendiendo la Filosofía Detrás de los Límites de Error

Antes de adentrarse en los detalles de implementación, vale la pena considerar por qué los límites de error existen como patrón y qué problemas resuelven. En la programación imperativa tradicional, el manejo de errores típicamente involucra bloques try-catch envueltos alrededor de operaciones específicas. Si bien este enfoque funciona para operaciones aisladas, las arquitecturas basadas en componentes presentan desafíos únicos.

Considera una aplicación Svelte típica: tienes un componente padre que renderiza múltiples hijos, cada uno potencialmente obteniendo datos, realizando cálculos o renderizando visualizaciones complejas. Cuando uno de estos hijos lanza un error durante el renderizado o mientras ejecuta efectos, ¿qué debería ocurrir? Sin límites de error, todo el árbol de componentes por encima del componente fallido se desmoronaría, a menudo derrumbando toda la aplicación o dejando a los usuarios frente a una pantalla en blanco.

Los límites de error proporcionan lo que podríamos llamar "contención del radio de explosión". Cuando un componente falla dentro de un límite, el límite captura el error, elimina el contenido fallido y opcionalmente renderiza una UI de respaldo, todo mientras el resto de tu aplicación continúa funcionando con normalidad. Este aislamiento es particularmente valioso en aplicaciones donde diferentes secciones operan de forma independiente: un widget de comentarios que falla no debería impedir que los usuarios lean un artículo, y un gráfico de analíticas roto no debería bloquear a los usuarios de todo su dashboard.

El elemento <svelte:boundary>, introducido en Svelte 5.3.0, trae este patrón a Svelte con una elegancia que se alinea con la filosofía de Svelte de mínimo código repetitivo y máxima expresividad.

La Anatomía de svelte:boundary

En su núcleo, <svelte:boundary> es un elemento especial que envuelve el contenido que deseas proteger. La estructura básica parece engañosamente simple:

<svelte:boundary><ProtectedContent /></svelte:boundary>

Sin embargo, esta forma mínima no hace nada útil: es un límite sin ningún manejo. Para que el límite gestione efectivamente los errores o los estados de carga, necesitas proporcionar una o más de sus tres propiedades principales: pending, failed y onerror. Cada una sirve un propósito distinto en el ciclo de vida del manejo de errores y estados de carga.

Cuando ocurre un error dentro de un <svelte:boundary>, el comportamiento del límite sigue una secuencia específica. Primero, si se proporciona un manejador onerror, recibe el error y una función de reinicio. Luego, si se proporciona un snippet failed, el límite elimina todo el contenido existente y renderiza el snippet en su lugar. Si no existe un snippet failed pero sí está presente onerror, el contenido simplemente se elimina.

Esta destrucción del contenido existente del límite es importante de entender: los errores no congelan la UI en un estado roto; desencadenan un reemplazo completo con el respaldo que hayas definido.

Manejo de Operaciones Asíncronas con el Snippet pending

Svelte 5 introdujo expresiones await en línea que te permiten escribir código asíncrono directamente en tus plantillas. Si bien esto es poderoso, genera una pregunta: ¿qué deberían ver los usuarios mientras esperan que las operaciones asíncronas se completen? El snippet pending proporciona la respuesta.

Cuando un <svelte:boundary> contiene expresiones await, el snippet pending se muestra inicialmente mientras esas promesas se están resolviendo:

<script>
	async function fetchUserProfile(userId) {
		const response = await fetch(`/api/users/${userId}`)
		if (!response.ok) throw new Error('Failed to load profile')
		return response.json()
	}

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

<svelte:boundary>
	<article class="user-profile">
		<h2>{await fetchUserProfile(userId).then((user) => user.name)}</h2>
		<p class="bio">{await fetchUserProfile(userId).then((user) => user.bio)}</p>
		<span class="joined">
			Member since {await fetchUserProfile(userId).then((user) =>
				new Date(user.createdAt).toLocaleDateString()
			)}
		</span>
	</article>

	{#snippet pending()}
		<article class="user-profile skeleton">
			<h2 class="skeleton-text">Loading...</h2>
			<p class="bio skeleton-text">&nbsp;</p>
			<span class="joined skeleton-text">&nbsp;</span>
		</article>
	{/snippet}
</svelte:boundary>

El snippet pending funciona como un estado de carga inicial: aparece cuando el límite se monta por primera vez y desaparece una vez que todas las expresiones await dentro del límite se han resuelto. Esto lo hace ideal para pantallas de esqueleto, indicadores de carga o contenido de marcador de posición que coincida con el diseño final.

Existe una distinción importante entre la carga inicial y las actualizaciones posteriores. El snippet pending solo aparece durante la fase de resolución inicial del límite. Si tus datos asíncronos se actualizan posteriormente (quizás debido a un cambio en una dependencia reactiva), el snippet pending no reaparecerá. Para manejar estados de carga durante actualizaciones posteriores, Svelte proporciona la runa $effect.pending(), que devuelve la cantidad de promesas pendientes dentro del límite actual:

<script>
	async function fetchData(query) {
		const response = await fetch(`/api/search?q=${encodeURIComponent(query)}`)
		return response.json()
	}

	let query = $state('')
	let debouncedQuery = $state('')

	$effect(() => {
		const timeout = setTimeout(() => {
			debouncedQuery = query
		}, 300)
		return () => clearTimeout(timeout)
	})
</script>

<input bind:value={query} placeholder="Search..." />

<svelte:boundary>
	<ul class="search-results">
		{#each await fetchData(debouncedQuery) as result}
			<li>{result.title}</li>
		{/each}
	</ul>

	{#snippet pending()}
		<p>Loading initial results...</p>
	{/snippet}
</svelte:boundary>

{#if $effect.pending()}
	<div class="loading-indicator">
		Updating results... ({$effect.pending()} pending)
	</div>
{/if}

Esta separación entre la carga inicial (snippet pending) y la carga por actualizaciones ($effect.pending()) te brinda un control detallado sobre tu UX de carga sin mezclar diferentes tipos de estados de carga.

Recuperación Elegante de Errores con el Snippet failed

El snippet failed es donde <svelte:boundary> verdaderamente demuestra su valor. Cuando ocurre un error durante el renderizado o mientras se ejecutan efectos dentro del límite, el snippet failed reemplaza completamente el contenido del límite, proporcionando un respaldo amigable para el usuario y las herramientas necesarias para la recuperación.

El snippet recibe dos argumentos: el objeto error en sí y una función reset que recrea el contenido del límite, dando a los usuarios la oportunidad de reintentar:

<script>
	import DataVisualization from './DataVisualization.svelte'

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

<svelte:boundary>
	<DataVisualization source={dataSource} />

	{#snippet failed(error, reset)}
		<div class="error-container" role="alert">
			<svg class="error-icon" viewBox="0 0 24 24" aria-hidden="true">
				<path
					d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-2h2v2zm0-4h-2V7h2v6z"
				/>
			</svg>

			<h3>Something went wrong</h3>
			<p class="error-message">{error.message}</p>

			<div class="error-actions">
				<button onclick={reset} class="retry-button"> Try again </button>
				<button
					onclick={() => navigator.clipboard.writeText(error.stack ?? error.message)}
					class="copy-button"
				>
					Copy error details
				</button>
			</div>

			{#if import.meta.env.DEV}
				<details class="error-details">
					<summary>Technical details</summary>
					<pre>{error.stack}</pre>
				</details>
			{/if}
		</div>
	{/snippet}
</svelte:boundary>

La función reset merece atención especial. Cuando se llama, destruye y recrea completamente el contenido del límite, volviendo a ejecutar cualquier lógica de inicialización, efectos y obtención de datos. Esto es poderoso, pero viene con consideraciones:

Todo el estado local dentro de los componentes del límite se pierde
Las solicitudes de red se volverán a ejecutar
Los efectos se volverán a ejecutar desde cero

Este comportamiento generalmente es deseable: si ocurrió un error, quieres un nuevo comienzo. Sin embargo, para los casos en los que deseas preservar algún estado entre reinicios, necesitarás elevar ese estado por encima del límite o usar contexto.

El snippet failed también puede pasarse explícitamente como una prop en lugar de declararse en línea, lo que habilita patrones poderosos para el manejo reutilizable de errores:

<script>
	import { errorFallback } from './error-handlers.js'
</script>

<svelte:boundary failed={errorFallback}><RiskyComponent /></svelte:boundary>

Manejo Programático de Errores con onerror

Mientras que el snippet failed maneja la representación visual de los errores, el manejador onerror proporciona un gancho para respuestas programáticas. Esto es esencial para el seguimiento de errores, analíticas y escenarios de recuperación complejos.

La función onerror recibe los mismos argumentos que el snippet failed: el error y una función de reinicio, lo que te permite implementar lógica sofisticada de manejo de errores:

<script>
	import { trackError } from './analytics.js'
	import { addToast } from './toast-store.svelte.js'

	function handleComponentError(error, reset) {
		// Track the error for monitoring
		trackError({
			component: 'UserDashboard',
			message: error.message,
			stack: error.stack,
			timestamp: Date.now(),
			url: window.location.href,
			userAgent: navigator.userAgent
		})

		// Show a toast notification
		addToast({
			type: 'error',
			message: "Something went wrong. We've been notified.",
			action: {
				label: 'Retry',
				callback: reset
			}
		})

		// Log to console in development
		if (import.meta.env.DEV) {
			console.error('Boundary caught error:', error)
		}
	}
</script>

<svelte:boundary onerror={handleComponentError}>
	<UserDashboard />

	{#snippet failed(error, reset)}
		<div class="dashboard-error">
			<p>Unable to load your dashboard.</p>
			<button onclick={reset}>Reload dashboard</button>
		</div>
	{/snippet}
</svelte:boundary>

Un patrón particularmente poderoso implica usar onerror para exponer el estado de error fuera del límite, permitiendo que componentes externos respondan a los errores:

<script>
	let boundaryError = $state(null)
	let boundaryReset = $state(() => {})

	function captureError(error, reset) {
		boundaryError = error
		boundaryReset = reset
	}

	function clearAndReset() {
		boundaryError = null
		boundaryReset()
	}
</script>

<!-- Error notification outside the boundary -->
{#if boundaryError}
	<aside class="global-error-banner" role="alert">
		<p>A component encountered an error: {boundaryError.message}</p>
		<button onclick={clearAndReset}>Dismiss and retry</button>
	</aside>
{/if}

<main>
	<svelte:boundary onerror={captureError}><ApplicationContent /></svelte:boundary>
</main>

Este patrón es particularmente valioso cuando tu UI de error necesita aparecer en una ubicación diferente a donde ocurrió el error, quizás en un área de notificaciones global o en un overlay modal.

Un comportamiento crítico que hay que entender: si ocurre un error dentro del propio manejador onerror (o si relanzas explícitamente el error), se propagará hacia el límite padre más cercano. Esto permite la escalación deliberada de errores cuando un límite determina que no puede manejar un error en particular:

<script>
	function handleError(error, reset) {
		// Only handle recoverable errors locally
		if (error.name === 'NetworkError' || error.name === 'TimeoutError') {
			// Handle recoverable errors
			console.log('Recoverable error, allowing retry')
			return
		}

		// Escalate critical errors to parent boundary
		throw error
	}
</script>

<svelte:boundary onerror={handleError}>
	<CriticalComponent />

	{#snippet failed(error, reset)}
		<!-- This only shows for recoverable errors -->
		<button onclick={reset}>Connection lost. Click to retry.</button>
	{/snippet}
</svelte:boundary>

Patrones Arquitectónicos Avanzados

Comprender la mecánica de <svelte:boundary> es solo el comienzo. El verdadero poder emerge cuando aplicas estos primitivos para resolver desafíos arquitectónicos complejos.

Estrategia de Límites Jerárquicos

Las aplicaciones grandes se benefician de múltiples capas de límites, cada una responsable de diferentes granularidades de fallo. Considera una aplicación de dashboard con múltiples widgets:

<!-- App.svelte - Root boundary catches catastrophic failures -->
<script>
	import Dashboard from './Dashboard.svelte'
	import { reportCriticalError } from './monitoring.js'
</script>

<svelte:boundary onerror={(e) => reportCriticalError(e)}>
	<Dashboard />

	{#snippet failed(error, reset)}
		<div class="app-crash">
			<h1>Application Error</h1>
			<p>We're sorry, but something went seriously wrong.</p>
			<button onclick={() => window.location.reload()}> Reload Application </button>
		</div>
	{/snippet}
</svelte:boundary>

<!-- Dashboard.svelte - Section boundaries isolate widget failures -->
<script>
	import Widget from './Widget.svelte'
	import { widgets } from './widget-config.js'
</script>

<div class="dashboard-grid">
	{#each widgets as widget (widget.id)}
		<svelte:boundary>
			<Widget config={widget} />

			{#snippet failed(error, reset)}
				<div class="widget-error">
					<p>Widget failed to load</p>
					<button onclick={reset}>Retry</button>
				</div>
			{/snippet}
		</svelte:boundary>
	{/each}
</div>

<!-- Widget.svelte - Fine-grained boundaries within widgets -->
<script>
	let { config } = $props()
</script>

<article class="widget">
	<header class="widget-header">
		<h3>{config.title}</h3>
	</header>

	<!-- Data section with its own boundary -->
	<svelte:boundary>
		<section class="widget-data">
			{#await config.fetchData()}
				<p>Loading data...</p>
			{:then data}
				<config.renderer {data} />
			{/await}
		</section>

		{#snippet pending()}
			<div class="widget-skeleton">Loading...</div>
		{/snippet}

		{#snippet failed(error, reset)}
			<div class="data-error">
				<p>Data unavailable</p>
				<button onclick={reset}>Refresh</button>
			</div>
		{/snippet}
	</svelte:boundary>

	<!-- Controls remain functional even if data fails -->
	<footer class="widget-controls">
		<button onclick={config.onSettings}>Settings</button>
	</footer>
</article>

Este enfoque de tres niveles garantiza que un fallo de carga de datos en un widget no afecte a otros widgets, y que un fallo de widget no derrumbe todo el dashboard, mientras se mantiene una red de seguridad a nivel de aplicación para fallos verdaderamente inesperados.

Creación de Componentes de Límite de Error Reutilizables

Para lograr consistencia en toda tu aplicación, puedes crear componentes envolventes que encapsulen tus patrones de manejo de errores:

<!-- ErrorBoundary.svelte -->
<script>
	import { getContext } from 'svelte'
	import type { Snippet } from 'svelte'

	interface Props {
		/** Component name for error tracking */
		name?: string
		/** Whether to show retry button in fallback */
		retryable?: boolean
		/** Custom fallback snippet */
		fallback?: Snippet<[Error, () => void]>
		/** Called when error is caught */
		onError?: (error: Error, componentName: string) => void
		/** Children content */
		children: Snippet
	}

	let {
		name = 'Unknown Component',
		retryable = true,
		fallback,
		onError,
		children
	}: Props = $props()

	// Get app-wide error reporter from context if available
	const reportError = getContext('errorReporter')

	function handleError(error: Error, reset: () => void) {
		// Report to monitoring
		if (reportError) {
			reportError({ error, component: name, timestamp: Date.now() })
		}

		// Call custom handler if provided
		onError?.(error, name)

		// Log in development
		if (import.meta.env.DEV) {
			console.error(`[${name}] Error:`, error)
		}
	}
</script>

<svelte:boundary onerror={handleError}>
	{@render children()}

	{#snippet failed(error, reset)}
		{#if fallback}
			{@render fallback(error, reset)}
		{:else}
			<div class="error-boundary-fallback" role="alert">
				<div class="error-icon">⚠️</div>
				<h4>Something went wrong</h4>
				<p>{error.message}</p>
				{#if retryable}
					<button onclick={reset} class="retry-btn"> Try again </button>
				{/if}
			</div>
		{/if}
	{/snippet}
</svelte:boundary>

<style>
	.error-boundary-fallback {
		padding: 1.5rem;
		border: 1px solid var(--color-error-border, #fca5a5);
		border-radius: 0.5rem;
		background: var(--color-error-bg, #fef2f2);
		text-align: center;
	}

	.error-icon {
		font-size: 2rem;
		margin-bottom: 0.5rem;
	}

	.error-boundary-fallback h4 {
		margin: 0 0 0.5rem;
		color: var(--color-error-heading, #991b1b);
	}

	.error-boundary-fallback p {
		margin: 0 0 1rem;
		color: var(--color-error-text, #b91c1c);
		font-size: 0.875rem;
	}

	.retry-btn {
		padding: 0.5rem 1rem;
		border: none;
		border-radius: 0.25rem;
		background: var(--color-error-button, #dc2626);
		color: white;
		cursor: pointer;
		font-weight: 500;
	}

	.retry-btn:hover {
		background: var(--color-error-button-hover, #b91c1c);
	}
</style>

El uso se vuelve limpio y consistente:

<script>
	import ErrorBoundary from './ErrorBoundary.svelte'
	import UserProfile from './UserProfile.svelte'
	import ActivityFeed from './ActivityFeed.svelte'
</script>

<div class="page-layout">
	<ErrorBoundary name="UserProfile" retryable={true}>
		<UserProfile />
	</ErrorBoundary>

	<ErrorBoundary name="ActivityFeed" retryable={true}>
		<ActivityFeed />
	</ErrorBoundary>
</div>

Combinación con Contexto para la Gestión de Errores a Nivel de Aplicación

Para aplicaciones grandes, puede que quieras un seguimiento centralizado de errores con la flexibilidad del manejo a nivel de componente:

<!-- ErrorProvider.svelte -->
<script>
	import { setContext } from 'svelte'

	interface ErrorRecord {
		id: string
		error: Error
		component: string
		timestamp: number
		resolved: boolean
	}

	let errors = $state<ErrorRecord[]>([])

	function reportError(details: { error: Error; component: string; timestamp: number }) {
		const record: ErrorRecord = {
			id: crypto.randomUUID(),
			...details,
			resolved: false
		}
		errors.push(record)

		// Could also send to external service here
		if (import.meta.env.PROD) {
			fetch('/api/errors', {
				method: 'POST',
				headers: { 'Content-Type': 'application/json' },
				body: JSON.stringify({
					message: details.error.message,
					stack: details.error.stack,
					component: details.component,
					timestamp: details.timestamp,
					url: window.location.href
				})
			}).catch(() => {
				// Silently fail - don't want error reporting to cause errors
			})
		}
	}

	function resolveError(id: string) {
		const error = errors.find((e) => e.id === id)
		if (error) error.resolved = true
	}

	function clearResolvedErrors() {
		errors = errors.filter((e) => !e.resolved)
	}

	setContext('errorReporter', reportError)
	setContext('errorResolver', resolveError)

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

<!-- Global error indicator -->
{#if errors.some((e) => !e.resolved)}
	<div class="error-indicator" role="status">
		{errors.filter((e) => !e.resolved).length} component(s) encountered errors
		<button onclick={clearResolvedErrors}>Clear resolved</button>
	</div>
{/if}

{@render children()}

Integración con el Manejo de Errores de SvelteKit

Al usar SvelteKit, <svelte:boundary> complementa en lugar de reemplazar el manejo de errores integrado de SvelteKit. Comprender cómo interactúan estos sistemas es crucial para construir aplicaciones robustas.

El sistema de errores de SvelteKit opera a nivel de ruta. Cuando ocurre un error en una función load o durante el renderizado del lado del servidor, SvelteKit renderiza la página +error.svelte más cercana. Esto sucede antes de que cualquier JavaScript del lado del cliente se ejecute, por lo que <svelte:boundary> no puede capturar estos errores: ocurren en una capa diferente de la aplicación.

Sin embargo, una vez que una página se ha cargado exitosamente y está ejecutándose en el cliente, <svelte:boundary> se convierte en tu herramienta principal para manejar errores en tiempo de ejecución:

<!-- +page.svelte -->
<script>
	import { page } from '$app/state'
	import InteractiveChart from './InteractiveChart.svelte'
	import CommentSection from './CommentSection.svelte'

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

<!-- This content loaded successfully from +page.server.js -->
<article>
	<h1>{data.article.title}</h1>
	<div class="content">
		{@html data.article.content}
	</div>
</article>

<!-- Interactive features wrapped in boundaries -->
<svelte:boundary>
	<InteractiveChart data={data.chartData} />

	{#snippet failed(error, reset)}
		<div class="chart-fallback">
			<p>Chart could not be rendered</p>
			<button onclick={reset}>Retry</button>
		</div>
	{/snippet}
</svelte:boundary>

<svelte:boundary>
	<CommentSection articleId={data.article.id} />

	{#snippet failed(error, reset)}
		<div class="comments-fallback">
			<p>Comments unavailable</p>
			<button onclick={reset}>Load comments</button>
		</div>
	{/snippet}
</svelte:boundary>

Este patrón garantiza que incluso si las funcionalidades interactivas del lado del cliente fallan, el contenido principal permanezca visible. El texto del artículo cargado desde el servidor se muestra normalmente, mientras que el gráfico interactivo y los comentarios, que podrían fallar debido a errores de JavaScript del lado del cliente o problemas de red, se degradan elegantemente.

Para errores que deberían navegar a los usuarios hacia una página de error, puedes usar el helper error de SvelteKit en combinación con los límites:

<script>
	import { error } from '@sveltejs/kit'
	import { goto } from '$app/navigation'

	function handleCriticalError(err, reset) {
		// For critical errors, navigate to error page
		if (err.name === 'AuthenticationError') {
			goto('/login?error=session_expired')
			return
		}

		if (err.name === 'NotFoundError') {
			error(404, { message: 'Resource not found' })
		}

		// For other errors, let the boundary handle it normally
	}
</script>

<svelte:boundary onerror={handleCriticalError}>
	<ProtectedContent />

	{#snippet failed(error, reset)}
		<!-- Only shown for non-critical errors -->
		<button onclick={reset}>Retry</button>
	{/snippet}
</svelte:boundary>

Errores Comunes y Cómo Evitarlos

La experiencia con los límites de error revela varios patrones que, aunque parecen razonables, conducen a comportamientos problemáticos.

1. Límites que Capturan Demasiado

Envolver toda tu aplicación en un único límite puede parecer una protección integral, pero crea una experiencia de usuario deficiente:

<!-- Don't do this -->
<svelte:boundary>
	<Header />
	<Navigation />
	<MainContent />
	<Footer />

	{#snippet failed(error, reset)}
		<p>Something went wrong. <button onclick={reset}>Retry</button></p>
	{/snippet}
</svelte:boundary>

Si algún componente falla, los usuarios pierden toda la UI, incluida la navegación que podría ayudarles a recuperarse. En su lugar, identifica los límites lógicos en tu aplicación y protégelos de forma independiente.

2. Asumir que los Efectos Son Seguros

Los límites capturan errores de los efectos ($effect), pero el momento puede ser sorprendente. Los efectos se ejecutan después de que el DOM se actualiza, por lo que un error en un efecto podría ocurrir después de que el componente se haya renderizado exitosamente una vez:

<script>
	let data = $state(null)

	$effect(() => {
		// This effect runs after initial render
		if (data.someProperty) {
			// Throws if data is null
			// ...
		}
	})
</script>

<svelte:boundary>
	<div>This renders, then the effect throws</div>

	{#snippet failed(error, reset)}
		<p>Error: {error.message}</p>
	{/snippet}
</svelte:boundary>

El componente se renderiza exitosamente, luego el efecto se ejecuta y lanza un error, y solo entonces el límite muestra el respaldo. Los usuarios podrían ver un destello de contenido antes de que aparezca el estado de error. Protégete contra esto validando el estado antes de acceder a las propiedades:

$effect(() => {
  if (!data) return; // Guard clause
  if (data.someProperty) {
    // Safe to access
  }
});

3. Olvidar que Reset Recrea Todo

Cuando se llama a reset, el boundary destruye y recrea todo el contenido. Esto significa:

Todas las instancias de componentes son destruidas y recreadas
Todo el estado local se pierde
Todos los efectos se desmontan y vuelven a ejecutarse
Todas las suscripciones se cancelan y se reestablecen

Si tenés estado que debería persistir entre resets, elevalo por encima del boundary:

<script>
	// This state survives resets
	let userPreferences = $state({ theme: 'light', fontSize: 14 })
</script>

<svelte:boundary>
	<!-- This component can fail and reset without losing preferences -->
	<Editor preferences={userPreferences} />

	{#snippet failed(error, reset)}
		<button onclick={reset}>Reload editor</button>
	{/snippet}
</svelte:boundary>

4. Bucles Infinitos de Reset

Si la causa de un error persiste, hacer clic en "reintentar" solo provocará el mismo error nuevamente, potencialmente frustrando a los usuarios con ciclos infinitos de fallo:

<script>
	let retryCount = $state(0)
	const MAX_RETRIES = 3

	function handleRetry(reset) {
		retryCount += 1
		if (retryCount < MAX_RETRIES) {
			reset()
		}
	}
</script>

<svelte:boundary>
	<UnstableComponent />

	{#snippet failed(error, reset)}
		{#if retryCount < MAX_RETRIES}
			<button onclick={() => handleRetry(reset)}>
				Retry ({MAX_RETRIES - retryCount} attempts remaining)
			</button>
		{:else}
			<div>
				<p>This component is currently unavailable.</p>
				<button
					onclick={() => {
						retryCount = 0
						reset()
					}}
				>
					Try fresh
				</button>
			</div>
		{/if}
	{/snippet}
</svelte:boundary>

5. No Manejar Errores en onerror

Si tu manejador onerror en sí mismo lanza un error, el error se propaga al boundary padre:

<script>
	function handleError(error, reset) {
		// This could throw if analytics service is unavailable
		analyticsService.trackError(error) // Dangerous!

		// Instead, wrap in try-catch:
		try {
			analyticsService.trackError(error)
		} catch (trackingError) {
			console.error('Failed to track error:', trackingError)
		}
	}
</script>

Pruebas de Error Boundaries

El manejo confiable de errores requiere pruebas exhaustivas. Aquí se explica cómo probar tus boundaries de manera efectiva:

<!-- ThrowingComponent.svelte - A test utility -->
<script>
	let { shouldThrow = false, errorMessage = 'Test error' } = $props()

	if (shouldThrow) {
		throw new Error(errorMessage)
	}
</script>

<div>Normal content</div>

// ErrorBoundary.test.js
import { render, screen, fireEvent } from '@testing-library/svelte'
import { describe, it, expect, vi } from 'vitest'
import BoundaryTest from './BoundaryTest.svelte'

describe('Error Boundary', () => {
	it('renders children when no error occurs', () => {
		render(BoundaryTest, { props: { shouldThrow: false } })
		expect(screen.getByText('Normal content')).toBeInTheDocument()
	})

	it('renders fallback when error occurs', () => {
		// Suppress error logging during test
		const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})

		render(BoundaryTest, { props: { shouldThrow: true } })
		expect(screen.getByText(/something went wrong/i)).toBeInTheDocument()
		expect(screen.queryByText('Normal content')).not.toBeInTheDocument()

		consoleSpy.mockRestore()
	})

	it('recovers when reset is called', async () => {
		const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})

		const { component } = render(BoundaryTest, { props: { shouldThrow: true } })

		// Update props to prevent error on retry
		await component.$set({ shouldThrow: false })

		// Click retry button
		await fireEvent.click(screen.getByRole('button', { name: /retry/i }))

		expect(screen.getByText('Normal content')).toBeInTheDocument()

		consoleSpy.mockRestore()
	})

	it('calls onerror handler with error details', () => {
		const errorHandler = vi.fn()
		const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})

		render(BoundaryTest, {
			props: {
				shouldThrow: true,
				errorMessage: 'Custom error',
				onError: errorHandler
			}
		})

		expect(errorHandler).toHaveBeenCalledWith(
			expect.objectContaining({ message: 'Custom error' }),
			expect.any(Function) // reset function
		)

		consoleSpy.mockRestore()
	})
})

Consideraciones de Rendimiento

Los error boundaries tienen una sobrecarga de rendimiento mínima cuando no ocurren errores—son esencialmente envoltorios transparentes. Sin embargo, tené en cuenta estas consideraciones:

Crear muchos boundaries agrega una ligera sobrecarga de memoria para almacenar el estado del boundary. Para listas con muchos elementos, considerá si cada elemento realmente necesita su propio boundary o si un único boundary alrededor de la lista es suficiente.

El snippet pending se renderiza inicialmente, por lo que una UI de estado pendiente compleja afecta el rendimiento de la carga inicial. Mantené los estados pendientes simples o usá skeleton screens que coincidan con tu layout para minimizar los saltos de diseño.

Cuando se llama a reset, todas las funciones de limpieza se ejecutan y los componentes se reinicializan. Para componentes con inicialización costosa (por ejemplo, contextos WebGL, estructuras de datos grandes), considerá almacenar en caché los recursos costosos por encima del boundary.

Conclusión

<svelte:boundary> representa un cambio de paradigma en la forma en que pensamos sobre el manejo de errores en aplicaciones basadas en componentes. En lugar de dejar que los errores se propaguen en cascada por el árbol de componentes, los boundaries proporcionan aislamiento, degradación elegante y mecanismos de recuperación que mantienen las aplicaciones funcionales incluso cuando componentes individuales fallan. Este enfoque arquitectónico—pensar en términos de dominios de fallo y contención del radio de impacto—hace que las aplicaciones sean más resilientes y proporciona mejores experiencias de usuario.

Los patrones explorados aquí—boundaries jerárquicos, componentes de boundary reutilizables, gestión centralizada de errores e integración con SvelteKit—demuestran que el manejo de errores no es una consideración secundaria, sino una preocupación de primera clase en la arquitectura de aplicaciones. Al combinar el poder declarativo de <svelte:boundary> con decisiones arquitectónicas bien pensadas, podés construir aplicaciones que fallen con elegancia, se recuperen de manera inteligente y mantengan la confianza del usuario incluso ante errores inesperados.

Puntos Clave

<svelte:boundary> proporciona aislamiento declarativo de errores introducido en Svelte 5.3.0, capturando errores de renderizado y fallas de efectos mientras permite que el resto de la aplicación continúe funcionando normalmente
Tres propiedades principales controlan el comportamiento: el snippet pending para estados de carga asíncrona inicial, el snippet failed para la UI de fallback de errores con argumentos de error y función reset, y el manejador onerror para el manejo programático de errores y el seguimiento de analíticas
El snippet pending solo aparece durante la resolución inicial, no durante actualizaciones posteriores—usá la rune $effect.pending() para rastrear estados de promesas en curso dentro de un boundary
La función reset destruye y recrea completamente el contenido del boundary, limpiando todo el estado local, re-ejecutando solicitudes de red y volviendo a ejecutar efectos desde cero—elevá el estado persistente por encima del boundary
La estrategia de boundaries jerárquicos previene fallos en cascada al colocar boundaries en múltiples granularidades: a nivel de aplicación para errores catastróficos, a nivel de sección para el aislamiento de funcionalidades y a nivel de componente para una protección más detallada
La escalada de errores mediante el relanzamiento en los manejadores onerror propaga los errores a los boundaries padre, permitiendo el manejo selectivo de errores recuperables mientras se escalan los fallos críticos
El manejo de errores a nivel de ruta de SvelteKit opera de forma separada de <svelte:boundary>, capturando errores de funciones load y de SSR antes de que el código del cliente se ejecute, mientras que los boundaries manejan errores en tiempo de ejecución del lado del cliente
Los errores comunes incluyen boundaries demasiado amplios, suposiciones sobre el timing de efectos, olvidar la destructividad del reset, bucles infinitos de reset por errores persistentes y excepciones no manejadas en los manejadores onerror

Ver También

Documentación Oficial de Svelte 5 - <svelte:boundary>
React Error Boundaries - El patrón que inspiró la implementación de Svelte
Manejo de Errores en SvelteKit - Comprensión de las páginas de error a nivel de ruta y errores en funciones load
$effect.pending() - Rastreo de promesas pendientes para estados de carga
Snippets de Svelte 5 - La sintaxis de snippets utilizada para los estados pending y failed
Buenas Prácticas de Monitoreo de Errores - Integración de servicios de seguimiento de errores con boundaries de Svelte
Testing Library para Svelte - Pruebas del comportamiento de error boundaries y flujos de recuperación
Rendimiento Web - Recuperación de Errores - Cómo el manejo de errores impacta las métricas de experiencia de usuario