feat: allow error boundaries to catch errors on the server

.changeset/cyan-walls-leave.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: allow error boundaries to catch errors on the server

packages/kit/src/core/config/index.spec.js

@@ -81,7 +81,8 @@ const get_defaults = (prefix = '') => ({
 			tracing: { server: false },
 			instrumentation: { server: false },
 			remoteFunctions: false,
-			forkPreloads: false
+			forkPreloads: false,
+			serverErrorBoundaries: false
 		},
 		files: {
 			src: join(prefix, 'src'),

packages/kit/src/core/config/options.js

@@ -133,7 +133,8 @@ const options = object(
 					server: boolean(false)
 				}),
 				remoteFunctions: boolean(false),
-				forkPreloads: boolean(false)
+				forkPreloads: boolean(false),
+				serverErrorBoundaries: boolean(false)
 			}),
 
 			files: object({

packages/kit/src/core/sync/sync.js

@@ -29,7 +29,7 @@ export function create(config) {
 
 	write_client_manifest(config.kit, manifest_data, `${output}/client`);
 	write_server(config, output);
-	write_root(manifest_data, output);
+	write_root(manifest_data, config, output);
 	write_all_types(config, manifest_data);
 	write_non_ambient(config.kit, manifest_data);
 

packages/kit/src/core/sync/write_root.js

@@ -2,11 +2,14 @@ import { dedent, isSvelte5Plus, write_if_changed } from './utils.js';
 
 /**
  * @param {import('types').ManifestData} manifest_data
+ * @param {import('types').ValidatedConfig} config
  * @param {string} output
  */
-export function write_root(manifest_data, output) {
+export function write_root(manifest_data, config, output) {
 	// TODO remove default layout altogether
 
+	const use_boundaries = config.kit.experimental.serverErrorBoundaries && isSvelte5Plus();
+
 	const max_depth = Math.max(
 		...manifest_data.routes.map((route) =>
 			route.page ? route.page.layouts.filter(Boolean).length + 1 : 0
@@ -25,19 +28,38 @@ export function write_root(manifest_data, output) {
 	${
 		isSvelte5Plus()
 			? `<!-- svelte-ignore binding_property_non_reactive -->
-		<Pyramid_${l} bind:this={components[${l}]} data={data_${l}} {form} params={page.params} />`
+		<Pyramid_${l} bind:this={components[${l}]} data={data_${l}} {form} params={page.params} {error} />`
 			: `<svelte:component this={constructors[${l}]} bind:this={components[${l}]} data={data_${l}} {form} params={page.params} />`
 	}`;
 
 	while (l--) {
+		let children = pyramid;
+
+		if (use_boundaries) {
+			// TODO I think we can check if an +error.svelte exists at this level, and only add the boundary if it does
+			children = dedent`
+				{#if errors[${l}]}
+					<svelte:boundary>
+						${pyramid}
+						{#snippet failed(error)}
+							{@const ErrorPage_${l} = errors[${l}]}
+							<ErrorPage_${l} {error} />
+						{/snippet}
+					</svelte:boundary>
+				{:else}
+					${pyramid}
+				{/if}
+			`;
+		}
+
 		pyramid = dedent`
 			{#if constructors[${l + 1}]}
 				${
 					isSvelte5Plus()
 						? dedent`{@const Pyramid_${l} = constructors[${l}]}
 						<!-- svelte-ignore binding_property_non_reactive -->
 						<Pyramid_${l} bind:this={components[${l}]} data={data_${l}} {form} params={page.params}>
-							${pyramid}
+							${children}
 						</Pyramid_${l}>`
 						: dedent`<svelte:component this={constructors[${l}]} bind:this={components[${l}]} data={data_${l}} params={page.params}>
 					${pyramid}
@@ -72,7 +94,7 @@ export function write_root(manifest_data, output) {
 				${
 					isSvelte5Plus()
 						? dedent`
-							let { stores, page, constructors, components = [], form, ${levels
+							let { stores, page, constructors, components = [], form, ${use_boundaries ? 'errors = [], error, ' : ''}${levels
 								.map((l) => `data_${l} = null`)
 								.join(', ')} } = $props();
 						`
@@ -108,7 +130,7 @@ export function write_root(manifest_data, output) {
 					isSvelte5Plus()
 						? dedent`
 							$effect(() => {
-								stores;page;constructors;components;form;${levels.map((l) => `data_${l}`).join(';')};
+								stores;page;constructors;components;form;${use_boundaries ? 'errors;error;' : ''}${levels.map((l) => `data_${l}`).join(';')};
 								stores.page.notify();
 							});
 						`

packages/kit/src/core/sync/write_server.js

@@ -50,6 +50,7 @@ export const options = {
 	root,
 	service_worker: ${has_service_worker},
 	service_worker_options: ${config.kit.serviceWorker.register ? s(config.kit.serviceWorker.options) : 'null'},
+	server_error_boundaries: ${s(!!config.kit.experimental.serverErrorBoundaries)},
 	templates: {
 		app: ({ head, body, assets, nonce, env }) => ${s(template)
 			.replace('%sveltekit.head%', '" + head + "')

packages/kit/src/exports/public.d.ts

@@ -512,6 +512,14 @@ export interface KitConfig {
 		 * @default false
 		 */
 		forkPreloads?: boolean;
+
+		/**
+		 * Whether to enable the experimental server error boundaries feature.
+		 * When enabled, `<svelte:boundary>` is used to wrap components at each level
+		 * where there's an `+error.svelte`, rendering the error page if the component fails.
+		 * @default false
+		 */
+		serverErrorBoundaries?: boolean;
 	};
 	/**
 	 * Where to find various files within your project.

packages/kit/src/exports/vite/index.js

@@ -350,7 +350,8 @@ async function kit({ svelte_config }) {
 				__SVELTEKIT_PATHS_RELATIVE__: s(kit.paths.relative),
 				__SVELTEKIT_CLIENT_ROUTING__: s(kit.router.resolution === 'client'),
 				__SVELTEKIT_HASH_ROUTING__: s(kit.router.type === 'hash'),
-				__SVELTEKIT_SERVER_TRACING_ENABLED__: s(kit.experimental.tracing.server)
+				__SVELTEKIT_SERVER_TRACING_ENABLED__: s(kit.experimental.tracing.server),
+				__SVELTEKIT_EXPERIMENTAL_USE_TRANSFORM_ERROR__: s(kit.experimental.serverErrorBoundaries)
 			};
 
 			if (is_build) {

packages/kit/src/runtime/client/client.js

@@ -589,7 +589,18 @@ async function initialize(result, target, hydrate) {
 		props: { ...result.props, stores, components },
 		hydrate,
 		// @ts-ignore Svelte 5 specific: asynchronously instantiate the component, i.e. don't call flushSync
-		sync: false
+		sync: false,
+		// @ts-ignore Svelte 5 specific: transformError allows to transform errors before they are passed to boundaries
+		transformError: __SVELTEKIT_EXPERIMENTAL_USE_TRANSFORM_ERROR__
+			? /** @param {unknown} error */ (error) =>
+					app.hooks.handleError({
+						error,
+						// @ts-expect-error TODO - what do we pass here? Nothing, and the types are adjusted accordingly in SvelteKit 3?
+						event: null,
+						status: get_status(error),
+						message: get_message(error)
+					})
+			: undefined
 	});
 
 	// Wait for a microtask in case svelte experimental async is enabled,
@@ -625,13 +636,23 @@ async function initialize(result, target, hydrate) {
  *   url: URL;
  *   params: Record<string, string>;
  *   branch: Array<import('./types.js').BranchNode | undefined>;
+ *   errors?: Array<import('types').CSRPageNodeLoader | undefined>;
  *   status: number;
  *   error: App.Error | null;
  *   route: import('types').CSRRoute | null;
  *   form?: Record<string, any> | null;
  * }} opts
  */
-function get_navigation_result_from_branch({ url, params, branch, status, error, route, form }) {
+async function get_navigation_result_from_branch({
+	url,
+	params,
+	branch,
+	errors,
+	status,
+	error,
+	route,
+	form
+}) {
 	/** @type {import('types').TrailingSlash} */
 	let slash = 'never';
 
@@ -666,6 +687,30 @@ function get_navigation_result_from_branch({ url, params, branch, status, error,
 		}
 	};
 
+	if (errors && __SVELTEKIT_EXPERIMENTAL_USE_TRANSFORM_ERROR__) {
+		let last_idx = -1;
+		result.props.errors = (
+			await Promise.all(
+				branch.map((b, i) => {
+					if (!b) return null;
+
+					// Find the closest error component up to the previous branch
+					while (i > last_idx && !errors[i]) i -= 1;
+					last_idx = i;
+					return errors[i]?.()
+						.then((e) => e.component)
+						.catch(() => undefined);
+				})
+			)
+		)
+			// filter out indexes where there was no branch, but keep indexes where there was a branch but no error component
+			.filter((e) => e !== null);
+
+		if (error) {
+			result.props.error = error;
+		}
+	}
+
 	if (form !== undefined) {
 		result.props.form = form;
 	}
@@ -1197,6 +1242,7 @@ async function load_route({ id, invalidating, url, params, route, preload }) {
 						url,
 						params,
 						branch: branch.slice(0, error_load.idx).concat(error_load.node),
+						errors,
 						status,
 						error,
 						route
@@ -1216,6 +1262,7 @@ async function load_route({ id, invalidating, url, params, route, preload }) {
 		url,
 		params,
 		branch,
+		errors,
 		status: 200,
 		error: null,
 		route,
@@ -1321,6 +1368,7 @@ async function load_root_error_page({ status, error, url, route }) {
 			branch: [root_layout, root_error],
 			status,
 			error,
+			errors: [],
 			route: null
 		});
 	} catch (error) {
@@ -2401,12 +2449,13 @@ export async function set_nearest_error_page(error, status = 500) {
 
 	const error_load = await load_nearest_error_page(current.branch.length, branch, route.errors);
 	if (error_load) {
-		const navigation_result = get_navigation_result_from_branch({
+		const navigation_result = await get_navigation_result_from_branch({
 			url,
 			params: current.params,
 			branch: branch.slice(0, error_load.idx).concat(error_load.node),
 			status,
 			error,
+			// do not set errors, we haven't changed the page so the previous ones are still current
 			route
 		});
 
@@ -2829,12 +2878,13 @@ async function _hydrate(
 			}
 		}
 
-		result = get_navigation_result_from_branch({
+		result = await get_navigation_result_from_branch({
 			url,
 			params,
 			branch,
 			status,
 			error,
+			errors: parsed_route?.errors, // TODO load earlier?
 			form,
 			route: parsed_route ?? null
 		});

packages/kit/src/runtime/client/types.d.ts

@@ -85,9 +85,11 @@ export type NavigationFinished = {
 	state: NavigationState;
 	props: {
 		constructors: Array<typeof SvelteComponent>;
+		errors?: Array<typeof SvelteComponent | undefined>;
 		components?: SvelteComponent[];
 		page: Page;
 		form?: Record<string, any> | null;
+		error?: App.Error;
 		[key: `data_${number}`]: Record<string, any>;
 	};
 };

packages/kit/src/runtime/server/page/index.js

@@ -299,6 +299,7 @@ export async function render_page(
 								},
 								status,
 								error,
+								// TODO error components
 								branch: layouts.concat({
 									node,
 									data: null,
@@ -337,6 +338,32 @@ export async function render_page(
 			});
 		}
 
+		/** @type {Array<import('types').SSRComponent | undefined> | undefined} */
+		let error_components;
+		if (options.server_error_boundaries && ssr) {
+			let last_idx = -1;
+			error_components = (
+				await Promise.all(
+					branch.map((b, i) => {
+						if (!b) return null;
+
+						// Find the closest error component up to the previous branch
+						while (i > last_idx && page.errors[i] === undefined) i -= 1;
+						last_idx = i;
+
+						const idx = page.errors[i];
+						if (idx == null) return undefined;
+
+						return manifest._.nodes[idx]?.()
+							.then((e) => e.component?.())
+							.catch(() => undefined);
+					})
+				)
+			)
+				// filter out indexes where there was no branch, but keep indexes where there was a branch but no error component
+				.filter((e) => e !== null);
+		}
+
 		return await render_response({
 			event,
 			event_state,
@@ -350,11 +377,11 @@ export async function render_page(
 			},
 			status,
 			error: null,
-			branch: ssr === false ? [] : compact(branch),
+			branch: !ssr ? [] : compact(branch),
 			action_result,
 			fetched,
-			data_serializer:
-				ssr === false ? server_data_serializer(event, event_state, options) : data_serializer
+			data_serializer: !ssr ? server_data_serializer(event, event_state, options) : data_serializer,
+			error_components
 		});
 	} catch (e) {
 		// a remote function could have thrown a redirect during render