Svelte SPA Router

Overview

The router provides a global error handling system that catches unhandled errors throughout your application and executes configured recovery strategies. It includes restart loop prevention, error filtering, and customizable error UI.

The error handler uses sessionStorage to track restart attempts and prevent infinite loops. It automatically resets after successful navigation.

Quick Start

1. Configure Error Handler

Configure in main.js

2. Add GlobalErrorHandler Component

Add to App.svelte

The GlobalErrorHandler component listens for all unhandled errors and executes the configured recovery strategy.

Recovery Strategies

navigateSafe - Navigate to Safe Route (Default)

Attempts to navigate to a known-good route when an error occurs:

Navigate to safe route

Use when: You have a reliable landing page that always works

restart - Full Application Restart

Reloads the entire application (hard refresh):

Restart application

Use when: Errors are likely due to stale state that a refresh would fix

showError - Display Error UI

Shows a full-page error display with recovery options:

Show error UI

Use when: You want users to see the error and choose their own recovery action

custom - Custom Error Handler

Implement your own error handling logic:

Custom error handler

Configuration Options

Option	Type	Default	Description
`strategy`	string	'navigateSafe'	Recovery strategy: 'navigateSafe', 'restart', 'showError', or 'custom'
`maxRestarts`	number	3	Maximum restart attempts before showing error UI
`safeRoute`	string	'/'	Route to navigate to when using 'navigateSafe' strategy
`showToast`	boolean	true	Show toast notification when error occurs
`ErrorComponent`	Component	ErrorDisplay	Custom error display component
`customHandler`	Function	undefined	Custom error handler function (required for 'custom' strategy)
`errorFilter`	RegExp \| string	undefined	Only handle errors matching this pattern

Error Filtering

Filter which errors trigger the error handler:

Filter by Error Message

Filter by String Match

Ignore Specific Errors

Restart Loop Prevention

The error handler uses sessionStorage to track restart attempts and prevent infinite loops:

Important: The restart counter is stored in sessionStorage under the key __svelte_spa_router_restart_count. It resets when:

User successfully navigates without errors
User closes the browser tab
User manually calls canRestart() and gets true

Helper Functions

restart()

Manually trigger an application restart (respects maxRestarts limit):

navigate()

Navigate to safe route (uses configured safeRoute):

showError()

Display the error UI component:

canRestart()

Check if restart is still allowed:

getRestartCount()

Get current restart attempt count:

Custom Error Component

Create a custom error display component:

Custom error display component

Use it in configuration:

Integration with Error Tracking Services

Sentry Integration

Custom Analytics

Default Error Display

The router includes a default ErrorDisplay.svelte component with:

Beautiful full-page error UI
Error message and stack trace (dev mode only)
Recovery action buttons (Go Home, Reload, Continue)
Warning when multiple errors detected
Responsive design

The default error display automatically hides technical details (stack traces, component stack) in production mode to avoid leaking implementation details.

Best Practices

1. Choose the Right Strategy

navigateSafe: Best for most applications with a reliable home page
restart: Good for state corruption issues
showError: Best for development or when users need to report errors
custom: When you need full control (e.g., error tracking integration)

2. Set Appropriate Restart Limits

3. Filter Noise

Some errors are expected and shouldn't trigger recovery:

4. Always Use GlobalErrorHandler Component

Don't forget to add <GlobalErrorHandler /> to your app root, otherwise errors won't be caught!