feat: add error boundaries

.changeset/polite-peaches-do.md

@@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+feat: adds error boundaries

packages/svelte/elements.d.ts

@@ -2026,6 +2026,10 @@ export interface SvelteHTMLElements {
 		[name: string]: any;
 	};
 	'svelte:head': { [name: string]: any };
+	'svelte:boundary': {
+		onerror?: (error: Error, reset: () => void) => void;
+		failed?: import('svelte').Snippet;
+	};
 
 	[name: string]: { [name: string]: any };
 }

packages/svelte/src/compiler/phases/1-parse/state/element.js

@@ -43,7 +43,8 @@ const meta_tags = new Map([
 	['svelte:element', 'SvelteElement'],
 	['svelte:component', 'SvelteComponent'],
 	['svelte:self', 'SvelteSelf'],
-	['svelte:fragment', 'SvelteFragment']
+	['svelte:fragment', 'SvelteFragment'],
+	['svelte:boundary', 'SvelteBoundary']
 ]);
 
 /** @param {Parser} parser */

packages/svelte/src/compiler/phases/3-transform/client/transform-client.js

@@ -48,6 +48,7 @@ import { SvelteComponent } from './visitors/SvelteComponent.js';
 import { SvelteDocument } from './visitors/SvelteDocument.js';
 import { SvelteElement } from './visitors/SvelteElement.js';
 import { SvelteFragment } from './visitors/SvelteFragment.js';
+import { SvelteBoundary } from './visitors/SvelteBoundary.js';
 import { SvelteHead } from './visitors/SvelteHead.js';
 import { SvelteSelf } from './visitors/SvelteSelf.js';
 import { SvelteWindow } from './visitors/SvelteWindow.js';
@@ -122,6 +123,7 @@ const visitors = {
 	SvelteDocument,
 	SvelteElement,
 	SvelteFragment,
+	SvelteBoundary,
 	SvelteHead,
 	SvelteSelf,
 	SvelteWindow,

packages/svelte/src/compiler/phases/3-transform/client/visitors/SvelteBoundary.js

@@ -0,0 +1,108 @@
+/** @import { BlockStatement, Statement, Property, Expression } from 'estree' */
+/** @import { AST } from '#compiler' */
+/** @import { ComponentContext } from '../types' */
+
+import * as b from '../../../../utils/builders.js';
+/**
+ * @param {AST.SvelteBoundary} node
+ * @param {ComponentContext} context
+ */
+export function SvelteBoundary(node, context) {
+	const nodes = [];
+	/** @type {Statement[]} */
+	const snippet_statements = [];
+	/** @type {Array<Property[] | Expression>} */
+	const props_and_spreads = [];
+
+	let has_spread = false;
+
+	const push_prop = (/** @type {Property} */ prop) => {
+		let current = props_and_spreads.at(-1);
+		if (Array.isArray(current)) {
+			current.push(prop);
+		}
+		const arr = [prop];
+		props_and_spreads.push(arr);
+	};
+
+	for (const attribute of node.attributes) {
+		if (attribute.type === 'SpreadAttribute') {
+			const value = /** @type {Expression} */ (context.visit(attribute.expression, context.state));
+			has_spread = true;
+
+			if (attribute.metadata.expression.has_state) {
+				props_and_spreads.push(b.thunk(value));
+			} else {
+				props_and_spreads.push(value);
+			}
+			continue;
+		}
+
+		// Skip non-attributes with a single value
+		if (
+			attribute.type !== 'Attribute' ||
+			attribute.value === true ||
+			Array.isArray(attribute.value)
+		) {
+			continue;
+		}
+
+		// Currently we only support `onerror` and `failed` props
+		if (attribute.name === 'onerror' || attribute.name === 'failed') {
+			const value = /** @type {Expression} */ (
+				context.visit(attribute.value.expression, context.state)
+			);
+
+			if (attribute.metadata.expression.has_state) {
+				push_prop(
+					b.prop('get', b.id(attribute.name), b.function(null, [], b.block([b.return(value)])))
+				);
+			} else {
+				push_prop(b.prop('init', b.id(attribute.name), value));
+			}
+		}
+	}
+
+	// Capture the `failed` implicit snippet prop
+	for (const child of node.fragment.nodes) {
+		if (child.type === 'SnippetBlock' && child.expression.name === 'failed') {
+			/** @type {Statement[]} */
+			const init = [];
+			const block_state = { ...context.state, init };
+			context.visit(child, block_state);
+			push_prop(b.prop('init', b.id('failed'), b.id('failed')));
+			snippet_statements.push(...init);
+		} else {
+			nodes.push(child);
+		}
+	}
+
+	const block = /** @type {BlockStatement} */ (
+		context.visit(
+			{
+				...node.fragment,
+				nodes
+			},
+			{ ...context.state }
+		)
+	);
+
+	const props_expression =
+		!has_spread && Array.isArray(props_and_spreads[0])
+			? b.object(props_and_spreads[0])
+			: props_and_spreads.length === 0
+				? b.object([])
+				: b.call(
+						'$.spread_props',
+						...props_and_spreads.map((p) => (Array.isArray(p) ? b.object(p) : p))
+					);
+
+	const boundary = b.stmt(
+		b.call('$.boundary', context.state.node, b.arrow([b.id('$$anchor')], block), props_expression)
+	);
+
+	context.state.template.push('<!>');
+	context.state.init.push(
+		snippet_statements ? b.block([...snippet_statements, boundary]) : boundary
+	);
+}

packages/svelte/src/compiler/phases/3-transform/server/transform-server.js

@@ -38,6 +38,7 @@ import { SvelteSelf } from './visitors/SvelteSelf.js';
 import { TitleElement } from './visitors/TitleElement.js';
 import { UpdateExpression } from './visitors/UpdateExpression.js';
 import { VariableDeclaration } from './visitors/VariableDeclaration.js';
+import { SvelteBoundary } from './visitors/SvelteBoundary.js';
 
 /** @type {Visitors} */
 const global_visitors = {
@@ -75,7 +76,8 @@ const template_visitors = {
 	SvelteFragment,
 	SvelteHead,
 	SvelteSelf,
-	TitleElement
+	TitleElement,
+	SvelteBoundary
 };
 
 /**

packages/svelte/src/compiler/phases/3-transform/server/visitors/SvelteBoundary.js

@@ -0,0 +1,20 @@
+/** @import { BlockStatement } from 'estree' */
+/** @import { AST } from '#compiler' */
+/** @import { ComponentContext } from '../types' */
+
+import {
+	BLOCK_CLOSE,
+	BLOCK_OPEN,
+	EMPTY_COMMENT
+} from '../../../../../internal/server/hydration.js';
+import * as b from '../../../../utils/builders.js';
+
+/**
+ * @param {AST.SvelteBoundary} node
+ * @param {ComponentContext} context
+ */
+export function SvelteBoundary(node, context) {
+	context.state.template.push(b.literal(BLOCK_OPEN));
+	context.state.template.push(/** @type {BlockStatement} */ (context.visit(node.fragment)));
+	context.state.template.push(b.literal(BLOCK_CLOSE));
+}

packages/svelte/src/compiler/phases/3-transform/utils.js

@@ -306,6 +306,7 @@ export function clean_nodes(
 				parent.type === 'SnippetBlock' ||
 				parent.type === 'EachBlock' ||
 				parent.type === 'SvelteComponent' ||
+				parent.type === 'SvelteBoundary' ||
 				parent.type === 'Component' ||
 				parent.type === 'SvelteSelf') &&
 			first &&

packages/svelte/src/compiler/types/template.d.ts

@@ -352,6 +352,11 @@ export namespace AST {
 		name: 'svelte:fragment';
 	}
 
+	export interface SvelteBoundary extends BaseElement {
+		type: 'SvelteBoundary';
+		name: 'svelte:boundary';
+	}
+
 	export interface SvelteHead extends BaseElement {
 		type: 'SvelteHead';
 		name: 'svelte:head';
@@ -499,7 +504,8 @@ export type ElementLike =
 	| AST.SvelteHead
 	| AST.SvelteOptionsRaw
 	| AST.SvelteSelf
-	| AST.SvelteWindow;
+	| AST.SvelteWindow
+	| AST.SvelteBoundary;
 
 export type TemplateNode =
 	| AST.Root

packages/svelte/src/internal/client/constants.js

@@ -4,21 +4,22 @@ export const RENDER_EFFECT = 1 << 3;
 export const BLOCK_EFFECT = 1 << 4;
 export const BRANCH_EFFECT = 1 << 5;
 export const ROOT_EFFECT = 1 << 6;
-export const UNOWNED = 1 << 7;
-export const DISCONNECTED = 1 << 8;
-export const CLEAN = 1 << 9;
-export const DIRTY = 1 << 10;
-export const MAYBE_DIRTY = 1 << 11;
-export const INERT = 1 << 12;
-export const DESTROYED = 1 << 13;
-export const EFFECT_RAN = 1 << 14;
+export const BOUNDARY_EFFECT = 1 << 7;
+export const UNOWNED = 1 << 8;
+export const DISCONNECTED = 1 << 9;
+export const CLEAN = 1 << 10;
+export const DIRTY = 1 << 11;
+export const MAYBE_DIRTY = 1 << 12;
+export const INERT = 1 << 13;
+export const DESTROYED = 1 << 14;
+export const EFFECT_RAN = 1 << 15;
 /** 'Transparent' effects do not create a transition boundary */
-export const EFFECT_TRANSPARENT = 1 << 15;
+export const EFFECT_TRANSPARENT = 1 << 16;
 /** Svelte 4 legacy mode props need to be handled with deriveds and be recognized elsewhere, hence the dedicated flag */
-export const LEGACY_DERIVED_PROP = 1 << 16;
-export const INSPECT_EFFECT = 1 << 17;
-export const HEAD_EFFECT = 1 << 18;
-export const EFFECT_HAS_DERIVED = 1 << 19;
+export const LEGACY_DERIVED_PROP = 1 << 17;
+export const INSPECT_EFFECT = 1 << 18;
+export const HEAD_EFFECT = 1 << 19;
+export const EFFECT_HAS_DERIVED = 1 << 20;
 
 export const STATE_SYMBOL = Symbol('$state');
 export const STATE_SYMBOL_METADATA = Symbol('$state metadata');

packages/svelte/src/internal/client/dom/blocks/boundary.js

@@ -0,0 +1,113 @@
+/** @import { Effect, TemplateNode, } from '#client' */
+
+import { BOUNDARY_EFFECT, EFFECT_TRANSPARENT } from '../../constants.js';
+import { block, branch, destroy_effect, pause_effect } from '../../reactivity/effects.js';
+import {
+	active_effect,
+	active_reaction,
+	component_context,
+	set_active_effect,
+	set_active_reaction,
+	set_component_context
+} from '../../runtime.js';
+import { hydrate_next, hydrate_node, hydrating } from '../hydration.js';
+import { queue_micro_task } from '../task.js';
+
+/**
+ * @param {Effect} boundary
+ * @param {() => void} fn
+ */
+function with_boundary(boundary, fn) {
+	var previous_effect = active_effect;
+	var previous_reaction = active_reaction;
+	var previous_ctx = component_context;
+	set_active_effect(boundary);
+	set_active_reaction(boundary);
+	set_component_context(boundary.ctx);
+	try {
+		fn();
+	} finally {
+		set_active_effect(previous_effect);
+		set_active_reaction(previous_reaction);
+		set_component_context(previous_ctx);
+	}
+}
+
+/**
+ * @param {TemplateNode} node
+ * @param {((anchor: Node) => void)} boundary_fn
+ * @param {{
+ * 	 onerror?: (error: Error, reset: () => void) => void,
+ *   failed?: (anchor: Node, error: () => Error, reset: () => () => void) => void
+ * }} props
+ * @returns {void}
+ */
+export function boundary(node, boundary_fn, props) {
+	var anchor = node;
+
+	/** @type {Effect | null} */
+	var boundary_effect;
+
+	block(() => {
+		var boundary = /** @type {Effect} */ (active_effect);
+
+		// We re-use the effect's fn property to avoid allocation of an additional field
+		boundary.fn = (/** @type { Error }} */ error) => {
+			var onerror = props.onerror;
+			let failed_snippet = props.failed;
+
+			if (boundary_effect) {
+				destroy_effect(boundary_effect);
+			}
+
+			// If we have nothing to capture the error then rethrow the error
+			// for another boundary to handle
+			if (!onerror && !failed_snippet) {
+				throw error;
+			}
+
+			// Handle resetting the error boundary
+			var reset = () => {
+				if (boundary_effect) {
+					pause_effect(boundary_effect);
+				}
+				with_boundary(boundary, () => {
+					boundary_effect = null;
+					boundary_effect = branch(() => boundary_fn(anchor));
+				});
+			};
+
+			// Handle the `onerror` event handler
+			if (onerror) {
+				onerror(error, reset);
+			}
+
+			// Handle the `failed` snippet fallback
+			if (failed_snippet) {
+				// Ensure we create the boundary branch after the catch event cycle finishes
+				queue_micro_task(() => {
+					with_boundary(boundary, () => {
+						boundary_effect = null;
+						boundary_effect = branch(() =>
+							failed_snippet(
+								anchor,
+								() => error,
+								() => reset
+							)
+						);
+					});
+				});
+			}
+		};
+
+		if (hydrating) {
+			hydrate_next();
+		}
+
+		boundary_effect = branch(() => boundary_fn(anchor));
+	}, EFFECT_TRANSPARENT | BOUNDARY_EFFECT);
+
+	if (hydrating) {
+		anchor = hydrate_node;
+	}
+}

packages/svelte/src/internal/client/dom/template.js

@@ -4,7 +4,6 @@ import { create_text, get_first_child } from './operations.js';
 import { create_fragment_from_html } from './reconciler.js';
 import { active_effect } from '../runtime.js';
 import { TEMPLATE_FRAGMENT, TEMPLATE_USE_IMPORT_NODE } from '../../../constants.js';
-import { queue_micro_task } from './task.js';
 
 /**
  * @param {TemplateNode} start

packages/svelte/src/internal/client/index.js

@@ -124,6 +124,7 @@ export {
 	update_store,
 	mark_store_binding
 } from './reactivity/store.js';
+export { boundary } from './dom/blocks/boundary.js';
 export { set_text } from './render.js';
 export {
 	get,