Tratamento Avançado de Erros e Isolamento de Componentes

No mundo das aplicações web modernas, erros não são exceções a serem temidas, mas realidades inevitáveis a serem gerenciadas com elegância. Uma falha visível ao usuário, uma rejeição de promise não tratada ou um componente que falha ao renderizar podem transformar uma aplicação refinada em uma experiência frustrante. O Svelte 5 introduz o elemento especial <svelte:boundary> como sua resposta a esse desafio — um mecanismo declarativo e combinável para isolar falhas e manter a estabilidade da aplicação mesmo quando componentes individuais encontram problemas.

Este guia explora o elemento <svelte:boundary> em profundidade abrangente, examinando não apenas sua sintaxe e propriedades, mas o raciocínio arquitetural por trás de um tratamento eficaz de erros em aplicações baseadas em componentes. Seja construindo dashboards complexos orientados a dados, ferramentas colaborativas em tempo real ou produtos voltados ao consumidor onde a confiabilidade é fundamental, entender os boundaries de erro mudará fundamentalmente como você aborda a resiliência em suas aplicações Svelte.

Entendendo a Filosofia por Trás dos Boundaries de Erro

Antes de mergulhar nos detalhes de implementação, vale considerar por que os boundaries de erro existem como padrão e quais problemas eles resolvem. Na programação imperativa tradicional, o tratamento de erros tipicamente envolve blocos try-catch envolvendo operações específicas. Embora essa abordagem funcione para operações isoladas, arquiteturas baseadas em componentes apresentam desafios únicos.

Considere uma aplicação Svelte típica: você tem um componente pai renderizando múltiplos filhos, cada um potencialmente buscando dados, realizando cálculos ou renderizando visualizações complexas. Quando um desses filhos lança um erro durante a renderização ou ao executar efeitos, o que deve acontecer? Sem boundaries de erro, toda a árvore de componentes acima do componente que falhou travaria, muitas vezes derrubando toda a aplicação ou deixando os usuários olhando para uma tela em branco.

Os boundaries de erro fornecem o que poderíamos chamar de "contenção do raio de impacto". Quando um componente falha dentro de um boundary, o boundary captura o erro, remove o conteúdo com falha e opcionalmente renderiza uma UI de fallback — tudo enquanto o restante da sua aplicação continua funcionando normalmente. Esse isolamento é particularmente valioso em aplicações onde diferentes seções operam de forma independente: um widget de comentários com falha não deve impedir os usuários de ler um artigo, e um gráfico de analytics quebrado não deve bloquear os usuários de acessar todo o seu dashboard.

O elemento <svelte:boundary>, introduzido no Svelte 5.3.0, traz esse padrão ao Svelte com uma elegância que se alinha à filosofia do Svelte de boilerplate mínimo e máxima expressividade.

A Anatomia do svelte:boundary

Em sua essência, <svelte:boundary> é um elemento especial que envolve o conteúdo que você deseja proteger. A estrutura básica parece enganosamente simples:

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

No entanto, essa forma mínima não faz nada útil — é um boundary sem nenhum tratamento. Para que o boundary realmente gerencie erros ou estados de carregamento, você precisa fornecer uma ou mais de suas três propriedades principais: pending, failed e onerror. Cada uma serve a um propósito distinto no ciclo de vida do gerenciamento de estados de erro e carregamento.

Quando um erro ocorre dentro de um <svelte:boundary>, o comportamento do boundary segue uma sequência específica. Primeiro, se um handler onerror for fornecido, ele recebe o erro e uma função de reset. Em seguida, se um snippet failed for fornecido, o boundary remove todo o conteúdo existente e renderiza o snippet em seu lugar. Se nenhum snippet failed existir mas onerror estiver presente, o conteúdo é simplesmente removido.

Essa destruição do conteúdo existente do boundary é importante de entender — os erros não congelam a UI em um estado quebrado; eles acionam uma substituição completa pelo fallback que você definiu.

Tratando Operações Assíncronas com o Snippet pending

O Svelte 5 introduziu expressões await inline que permitem escrever código assíncrono diretamente nos seus templates. Embora poderoso, isso cria uma questão: o que os usuários devem ver enquanto aguardam a conclusão de operações assíncronas? O snippet pending fornece a resposta.

Quando um <svelte:boundary> contém expressões await, o snippet pending é exibido inicialmente enquanto essas promises estão sendo resolvidas:

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

O snippet pending funciona como um estado de carregamento inicial — ele aparece quando o boundary é montado pela primeira vez e desaparece assim que todas as expressões await dentro do boundary foram resolvidas. Isso o torna ideal para skeleton screens, spinners de carregamento ou conteúdo placeholder que corresponde ao layout final.

Uma distinção importante existe entre o carregamento inicial e as atualizações subsequentes. O snippet pending só aparece durante a fase de resolução inicial do boundary. Se seus dados assíncronos forem atualizados posteriormente (talvez devido a uma dependência reativa sendo alterada), o snippet pending não reaparecerá. Para tratar estados de carregamento durante atualizações subsequentes, o Svelte fornece a rune $effect.pending(), que retorna a contagem de promises pendentes dentro do boundary atual:

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

Essa separação entre carregamento inicial (snippet pending) e carregamento de atualização ($effect.pending()) fornece controle refinado sobre sua UX de carregamento sem confundir diferentes tipos de estados de carregamento.

Recuperação Elegante de Erros com o Snippet failed

O snippet failed é onde <svelte:boundary> demonstra verdadeiramente seu valor. Quando um erro ocorre durante a renderização ou ao executar efeitos dentro do boundary, o snippet failed substitui completamente o conteúdo do boundary, fornecendo um fallback amigável ao usuário e as ferramentas necessárias para recuperação.

O snippet recebe dois argumentos: o próprio objeto error e uma função reset que recria o conteúdo do boundary, dando aos usuários a oportunidade de tentar novamente:

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

A função reset merece atenção especial. Quando chamada, ela destrói e recria completamente o conteúdo do boundary, re-executando qualquer lógica de inicialização, efeitos e busca de dados. Isso é poderoso, mas vem com considerações:

Qualquer estado local dentro dos componentes do boundary é perdido
Requisições de rede serão re-executadas
Efeitos serão executados novamente do zero

Esse comportamento geralmente é desejável — se um erro ocorreu, você quer um recomeço limpo. No entanto, para casos onde você deseja preservar algum estado entre resets, você precisará elevar esse estado acima do boundary ou usar contexto.

O snippet failed também pode ser passado explicitamente como uma prop em vez de declarado inline, o que habilita padrões poderosos para tratamento de erros reutilizável:

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

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

Tratamento Programático de Erros com onerror

Enquanto o snippet failed trata da representação visual dos erros, o handler onerror fornece um gancho para respostas programáticas. Isso é essencial para rastreamento de erros, analytics e cenários de recuperação complexos.

A função onerror recebe os mesmos argumentos que o snippet failed — o erro e uma função de reset — permitindo implementar lógica sofisticada de tratamento de erros:

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

Um padrão particularmente poderoso envolve usar onerror para expor o estado de erro fora do boundary, permitindo que componentes externos respondam aos erros:

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

Esse padrão é particularmente valioso quando sua UI de erro precisa aparecer em um local diferente de onde o erro ocorreu — talvez em uma área global de notificações ou em uma sobreposição modal.

Um comportamento crítico a entender: se um erro ocorrer dentro do próprio handler onerror (ou se você relançar explicitamente o erro), ele se propagará para o próximo boundary pai. Isso habilita a escalada deliberada de erros quando um boundary determina que não pode tratar um erro específico:

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

Padrões Arquiteturais Avançados

Entender a mecânica do <svelte:boundary> é apenas o começo. O poder real emerge quando você aplica esses primitivos para resolver desafios arquiteturais complexos.

Estratégia de Boundary Hierárquico

Aplicações grandes se beneficiam de múltiplas camadas de boundary, cada uma responsável por diferentes granularidades de falha. Considere uma aplicação de dashboard com múltiplos 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>

Essa abordagem de três camadas garante que uma falha de carregamento de dados em um widget não afete outros widgets, e uma falha de widget não trave o dashboard inteiro, enquanto ainda mantém uma rede de segurança no nível da aplicação para falhas verdadeiramente inesperadas.

Criando Componentes de Boundary de Erro Reutilizáveis

Para consistência em toda a sua aplicação, você pode criar componentes wrapper que encapsulam seus padrões de tratamento de erros:

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

O uso se torna limpo e 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>

Combinando com Contexto para Gerenciamento de Erros em Toda a Aplicação

Para aplicações grandes, você pode querer rastreamento centralizado de erros com a flexibilidade do tratamento em nível 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()}

Integração com o Tratamento de Erros do SvelteKit

Ao usar o SvelteKit, <svelte:boundary> complementa em vez de substituir o tratamento de erros integrado do SvelteKit. Entender como esses sistemas interagem é crucial para construir aplicações robustas.

O sistema de erros do SvelteKit opera no nível de rota. Quando um erro ocorre em uma função load ou durante a renderização no servidor, o SvelteKit renderiza a página +error.svelte mais próxima. Isso acontece antes de qualquer JavaScript do lado do cliente ser executado, portanto <svelte:boundary> não pode capturar esses erros — eles ocorrem em uma camada diferente da aplicação.

No entanto, uma vez que uma página carregou com sucesso e está sendo executada no cliente, <svelte:boundary> se torna sua principal ferramenta para tratar erros em tempo de execução:

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

Esse padrão garante que mesmo se os recursos interativos do lado do cliente falharem, o conteúdo principal permaneça visível. O texto do artigo carregado do servidor é exibido normalmente enquanto o gráfico interativo e os comentários — que podem falhar devido a erros de JavaScript no lado do cliente ou problemas de rede — degradam graciosamente.

Para erros que devem navegar os usuários para uma página de erro, você pode usar o helper error do SvelteKit em combinação com boundaries:

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

Armadilhas Comuns e Como Evitá-las

A experiência com boundaries de erro revela vários padrões que, embora aparentemente razoáveis, levam a comportamentos problemáticos.

1. Boundaries que Capturam Demais

Envolver toda a sua aplicação em um único boundary pode parecer uma proteção abrangente, mas cria uma experiência de usuário ruim:

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

Se qualquer componente falhar, os usuários perdem toda a UI, incluindo a navegação que poderia ajudá-los a se recuperar. Em vez disso, identifique limites lógicos em sua aplicação e proteja-os de forma independente.

2. Assumir que Efeitos São Seguros

Boundaries capturam erros de efeitos ($effect), mas o timing pode ser surpreendente. Efeitos são executados após as atualizações do DOM, portanto um erro em um efeito pode ocorrer depois que o componente foi renderizado com sucesso uma 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>

O componente renderiza com sucesso, depois o efeito é executado e lança uma exceção, e somente então o boundary exibe o fallback. Os usuários podem ver um flash de conteúdo antes do estado de erro aparecer. Proteja-se contra isso validando o estado antes de acessar propriedades:

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

3. Esquecer que Reset Recria Tudo

Quando reset é chamado, o boundary destrói e recria todo o conteúdo. Isso significa que:

Todas as instâncias de componente são destruídas e recriadas
Todo o estado local é perdido
Todos os effects são desmontados e re-executados
Todas as assinaturas são canceladas e reestabelecidas

Se você tiver um estado que deve persistir entre resets, eleve-o para acima do 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. Loops Infinitos de Reset

Se a causa do erro persistir, clicar em "tentar novamente" causará o mesmo erro novamente, potencialmente frustrando os usuários com ciclos infinitos de falha:

<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. Não Tratar Erros no onerror

Se o seu handler onerror lançar uma exceção, o erro se propaga para o boundary pai:

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

Testando Error Boundaries

O tratamento confiável de erros requer testes minuciosos. Veja como testar seus boundaries de forma eficaz:

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

Considerações de Performance

Error boundaries têm overhead de desempenho mínimo quando nenhum erro ocorre — eles são essencialmente wrappers transparentes. No entanto, tenha em mente as seguintes considerações:

Criar muitos boundaries adiciona um leve overhead de memória para armazenar o estado do boundary. Para listas com muitos itens, considere se cada item realmente precisa de seu próprio boundary ou se um único boundary ao redor da lista é suficiente.

O snippet pending é renderizado inicialmente, portanto, uma UI de pending complexa afeta o desempenho do carregamento inicial. Mantenha os estados de pending simples ou use skeleton screens que correspondam ao seu layout para minimizar as mudanças de layout.

Quando reset é chamado, todas as funções de limpeza são executadas e os componentes são reinicializados. Para componentes com inicialização custosa (por exemplo, contextos WebGL, grandes estruturas de dados), considere fazer cache dos recursos custosos acima do boundary.

Conclusão

<svelte:boundary> representa uma mudança de paradigma na forma como pensamos sobre o tratamento de erros em aplicações baseadas em componentes. Em vez de deixar os erros se propagarem pela árvore de componentes, os boundaries fornecem isolamento, degradação graciosa e mecanismos de recuperação que mantêm as aplicações funcionais mesmo quando componentes individuais falham. Essa abordagem arquitetural — pensar em termos de domínios de falha e contenção do raio de impacto — torna as aplicações mais resilientes e proporciona melhores experiências ao usuário.

Os padrões explorados aqui — boundaries hierárquicos, componentes de boundary reutilizáveis, gerenciamento centralizado de erros e integração com o SvelteKit — demonstram que o tratamento de erros não é uma preocupação secundária, mas uma questão de primeira classe na arquitetura de aplicações. Ao combinar o poder declarativo do <svelte:boundary> com decisões arquiteturais bem pensadas, você pode criar aplicações que falham graciosamente, se recuperam de forma inteligente e mantêm a confiança do usuário mesmo diante de erros inesperados.

Principais Conclusões

<svelte:boundary> fornece isolamento declarativo de erros introduzido no Svelte 5.3.0, capturando erros de renderização e falhas de effects enquanto permite que o restante da aplicação continue funcionando normalmente
Três propriedades principais controlam o comportamento: o snippet pending para estados de carregamento assíncrono inicial, o snippet failed para a UI de fallback de erro com argumentos de erro e função de reset, e o handler onerror para tratamento programático de erros e rastreamento de analytics
O snippet pending só aparece durante a resolução inicial, não durante atualizações subsequentes — use a rune $effect.pending() para rastrear estados de promise em andamento dentro de um boundary
A função reset destrói e recria completamente o conteúdo do boundary, limpando todo o estado local, re-executando requisições de rede e re-executando effects do zero — eleve o estado persistente para acima do boundary
A estratégia de boundary hierárquico previne falhas em cascata ao posicionar boundaries em múltiplas granularidades: nível de aplicação para erros catastróficos, nível de seção para isolamento de funcionalidades e nível de componente para proteção refinada
Escalada de erros via relançamento em handlers onerror propaga erros para boundaries pai, permitindo o tratamento seletivo de erros recuperáveis enquanto escala falhas críticas
O tratamento de erros em nível de rota do SvelteKit opera separadamente do <svelte:boundary>, capturando erros de funções de load e SSR antes que o código do cliente seja executado, enquanto os boundaries lidam com erros de tempo de execução no lado do cliente
Armadilhas comuns incluem boundaries excessivamente abrangentes, suposições sobre o timing dos effects, esquecer a destrutividade do reset, loops infinitos de reset causados por erros persistentes e exceções não tratadas em handlers onerror

Veja Também

Documentação Oficial do Svelte 5 - <svelte:boundary>
React Error Boundaries - O padrão que inspirou a implementação do Svelte
Tratamento de Erros no SvelteKit - Entendendo páginas de erro em nível de rota e erros de funções de load
$effect.pending() - Rastreando promises pendentes para estados de carregamento
Snippets do Svelte 5 - A sintaxe de snippet usada para os estados pending e failed
Boas Práticas de Monitoramento de Erros - Integrando serviços de rastreamento de erros com boundaries do Svelte
Testing Library para Svelte - Testando o comportamento de error boundaries e fluxos de recuperação
Performance Web - Recuperação de Erros - Como o tratamento de erros impacta as métricas de experiência do usuário