feat: custom renderers API

.changeset/salty-steaks-wash.md

@@ -0,0 +1,5 @@
+---
+'svelte': minor
+---
+
+feat: custom renderer api

documentation/docs/98-reference/.generated/client-errors.md

@@ -197,6 +197,12 @@ Failed to hydrate the application
 Could not `{@render}` snippet due to the expression being `null` or `undefined`. Consider using optional chaining `{@render snippet?.()}`
 ```
 
+### invalid_snippet_in_custom_renderer
+
+```
+`createRawSnippet` cannot be used with a custom renderer
+```
+
 ### lifecycle_legacy_only
 
 ```
@@ -229,6 +235,12 @@ The `%rune%` rune is only available inside `.svelte` and `.svelte.js/ts` files
 
 This restriction only applies when using the `experimental.async` option, which will be active by default in Svelte 6.
 
+### snippet_renderer_mismatch
+
+```
+A snippet created in a component with a custom renderer cannot be rendered by a different renderer
+```
+
 ### state_descriptors_fixed
 
 ```

documentation/docs/98-reference/.generated/compile-errors.md

@@ -605,6 +605,12 @@ Cannot use `await` in deriveds and template expressions, or at the top level of
 Imports of `svelte/internal/*` are forbidden. It contains private runtime code which is subject to change without notice. If you're importing from `svelte/internal/*` to work around a limitation of Svelte, please open an issue at https://github.com/sveltejs/svelte and explain your use case
 ```
 
+### incompatible_with_custom_renderer
+
+```
+%message% is not compatible with `customRenderer`
+```
+
 ### inspect_trace_generator
 
 ```

packages/svelte/messages/client-errors/errors.md

@@ -151,6 +151,10 @@ This can happen if you render a hydratable on the client that was not rendered o
 
 > Could not `{@render}` snippet due to the expression being `null` or `undefined`. Consider using optional chaining `{@render snippet?.()}`
 
+## invalid_snippet_in_custom_renderer
+
+> `createRawSnippet` cannot be used with a custom renderer
+
 ## lifecycle_legacy_only
 
 > `%name%(...)` cannot be used in runes mode
@@ -173,6 +177,10 @@ This can happen if you render a hydratable on the client that was not rendered o
 
 This restriction only applies when using the `experimental.async` option, which will be active by default in Svelte 6.
 
+## snippet_renderer_mismatch
+
+> A snippet created in a component with a custom renderer cannot be rendered by a different renderer
+
 ## state_descriptors_fixed
 
 > Property descriptors defined on `$state` objects must contain `value` and always be `enumerable`, `configurable` and `writable`.

packages/svelte/messages/compile-errors/template.md

@@ -263,6 +263,10 @@ The same applies to components:
 
 > `<%name%>` does not support non-event attributes or spread attributes
 
+## incompatible_with_custom_renderer
+
+> %message% is not compatible with `customRenderer`
+
 ## js_parse_error
 
 > %message%

packages/svelte/package.json

@@ -59,6 +59,9 @@
     "./internal/disclose-version": {
       "default": "./src/internal/disclose-version.js"
     },
+    "./internal/init-operations": {
+      "default": "./src/internal/init-operations.js"
+    },
     "./internal/flags/async": {
       "default": "./src/internal/flags/async.js"
     },
@@ -91,6 +94,10 @@
       "types": "./types/index.d.ts",
       "default": "./src/reactivity/window/index.js"
     },
+    "./renderer": {
+      "types": "./types/index.d.ts",
+      "default": "./src/renderer/index.js"
+    },
     "./server": {
       "types": "./types/index.d.ts",
       "default": "./src/server/index.js"

packages/svelte/renderer.d.ts

@@ -0,0 +1 @@
+import './types/index.js';

packages/svelte/scripts/generate-types.js

@@ -8,7 +8,16 @@ const pkg = JSON.parse(fs.readFileSync(`${dir}/package.json`, 'utf-8'));
 
 // For people not using moduleResolution: 'bundler', we need to generate these files. Think about removing this in Svelte 6 or 7
 // It may look weird, but the imports MUST be ending with index.js to be properly resolved in all TS modes
-for (const name of ['action', 'animate', 'easing', 'motion', 'store', 'transition', 'legacy']) {
+for (const name of [
+	'action',
+	'animate',
+	'easing',
+	'motion',
+	'store',
+	'transition',
+	'legacy',
+	'renderer'
+]) {
 	fs.writeFileSync(`${dir}/${name}.d.ts`, "import './types/index.js';\n");
 }
 
@@ -44,6 +53,7 @@ await createBundle({
 		[`${pkg.name}/motion`]: `${dir}/src/motion/public.d.ts`,
 		[`${pkg.name}/reactivity`]: `${dir}/src/reactivity/index-client.js`,
 		[`${pkg.name}/reactivity/window`]: `${dir}/src/reactivity/window/index.js`,
+		[`${pkg.name}/renderer`]: `${dir}/src/internal/client/custom-renderer/index.js`,
 		[`${pkg.name}/server`]: `${dir}/src/server/index.d.ts`,
 		[`${pkg.name}/store`]: `${dir}/src/store/public.d.ts`,
 		[`${pkg.name}/transition`]: `${dir}/src/transition/public.d.ts`,

packages/svelte/src/compiler/errors.js

@@ -1176,6 +1176,16 @@ export function illegal_element_attribute(node, name) {
 	e(node, 'illegal_element_attribute', `\`<${name}>\` does not support non-event attributes or spread attributes\nhttps://svelte.dev/e/illegal_element_attribute`);
 }
 
+/**
+ * %message% is not compatible with `customRenderer`
+ * @param {null | number | NodeLike} node
+ * @param {string} message
+ * @returns {never}
+ */
+export function incompatible_with_custom_renderer(node, message) {
+	e(node, 'incompatible_with_custom_renderer', `${message} is not compatible with \`customRenderer\`\nhttps://svelte.dev/e/incompatible_with_custom_renderer`);
+}
+
 /**
  * %message%
  * @param {null | number | NodeLike} node

packages/svelte/src/compiler/index.js

@@ -28,15 +28,23 @@ export function compile(source, options) {
 
 	let parsed = _parse(source);
 
-	const { customElement: customElementOptions, ...parsed_options } = parsed.options || {};
+	const {
+		customElement: customElementOptions,
+		customRenderer: custom_renderer,
+		...parsed_options
+	} = parsed.options || {};
 
 	/** @type {ValidatedCompileOptions} */
 	const combined_options = {
 		...validated,
 		...parsed_options,
 		customElementOptions,
 		css: 'css' in parsed_options ? () => parsed_options.css ?? 'external' : validated.css,
-		runes: 'runes' in parsed_options ? () => parsed_options.runes : validated.runes
+		runes: 'runes' in parsed_options ? () => parsed_options.runes : validated.runes,
+		experimental: {
+			...validated.experimental,
+			...(custom_renderer !== undefined ? { customRenderer: () => custom_renderer } : {})
+		}
 	};
 
 	if (parsed.metadata.ts) {

packages/svelte/src/compiler/migrate/index.js

@@ -149,7 +149,8 @@ export function migrate(source, { filename, use_ts } = {}) {
 			css: 'css' in parsed_options ? () => parsed_options.css ?? 'external' : () => 'external',
 			runes: 'runes' in parsed_options ? () => parsed_options.runes : () => undefined,
 			experimental: {
-				async: true
+				async: true,
+				customRenderer: () => undefined
 			}
 		};
 

packages/svelte/src/compiler/phases/1-parse/read/options.js

@@ -36,6 +36,10 @@ export default function read_options(node) {
 				e.svelte_options_deprecated_tag(attribute);
 				break; // eslint doesn't know this is unnecessary
 			}
+			case 'customRenderer': {
+				component_options.customRenderer = get_static_value(attribute);
+				break;
+			}
 			case 'customElement': {
 				/** @type {AST.SvelteOptions['customElement']} */
 				const ce = {};
@@ -193,6 +197,14 @@ export default function read_options(node) {
 		}
 	}
 
+	if (component_options.css === 'injected' && component_options.customRenderer !== undefined) {
+		// Find the css attribute node for the error position
+		const css_attribute = node.attributes.find(
+			(/** @type {any} */ a) => a.type === 'Attribute' && a.name === 'css'
+		);
+		e.incompatible_with_custom_renderer(css_attribute ?? node, "`css: 'injected'`");
+	}
+
 	return component_options;
 }
 

packages/svelte/src/compiler/phases/2-analyze/index.js

@@ -467,6 +467,12 @@ export function analyze_component(root, source, options) {
 
 	const custom_element_from_option = options.customElement({ filename: options.filename });
 	const css = options.css({ filename: options.filename });
+	const custom_renderer = options.experimental.customRenderer?.({ filename: options.filename });
+
+	if (css === 'injected' && custom_renderer !== undefined) {
+		e.incompatible_with_custom_renderer(null, "`css: 'injected'`");
+	}
+
 	const custom_element = options.customElementOptions ?? custom_element_from_option;
 	const is_custom_element = !!options.customElementOptions || custom_element_from_option;
 
@@ -529,6 +535,7 @@ export function analyze_component(root, source, options) {
 		event_directive_node: null,
 		uses_event_attributes: false,
 		custom_element,
+		custom_renderer,
 		inject_styles: css === 'injected' || is_custom_element,
 		accessors:
 			is_custom_element ||

packages/svelte/src/compiler/phases/2-analyze/visitors/AnimateDirective.js

@@ -7,6 +7,10 @@ import * as e from '../../../errors.js';
  * @param {Context} context
  */
 export function AnimateDirective(node, context) {
+	if (context.state.analysis.custom_renderer) {
+		e.incompatible_with_custom_renderer(node, '`animate:`');
+	}
+
 	context.next({ ...context.state, expression: node.metadata.expression });
 
 	if (node.metadata.expression.has_await) {

packages/svelte/src/compiler/phases/2-analyze/visitors/Attribute.js

@@ -59,8 +59,11 @@ export function Attribute(node, context) {
 				context.state.analysis.uses_event_attributes = true;
 			}
 
-			node.metadata.delegated =
-				parent?.type === 'RegularElement' && can_delegate_event(node.name.slice(2));
+			// we can't delegate event handlers in a non dom environment
+			if (!context.state.analysis.custom_renderer) {
+				node.metadata.delegated =
+					parent?.type === 'RegularElement' && can_delegate_event(node.name.slice(2));
+			}
 		}
 	}
 }

packages/svelte/src/compiler/phases/2-analyze/visitors/BindDirective.js

@@ -27,6 +27,9 @@ export function BindDirective(node, context) {
 		parent?.type === 'SvelteDocument' ||
 		parent?.type === 'SvelteBody'
 	) {
+		if (context.state.analysis.custom_renderer) {
+			e.incompatible_with_custom_renderer(node, '`bind:`');
+		}
 		if (node.name in binding_properties) {
 			const property = binding_properties[node.name];
 			if (property.valid_elements && !property.valid_elements.includes(parent.name)) {

packages/svelte/src/compiler/phases/2-analyze/visitors/ExpressionTag.js

@@ -11,7 +11,7 @@ import { mark_subtree_dynamic } from './shared/fragment.js';
 export function ExpressionTag(node, context) {
 	const in_template = context.path.at(-1)?.type === 'Fragment';
 
-	if (in_template && context.state.parent_element) {
+	if (in_template && context.state.parent_element && !context.state.analysis.custom_renderer) {
 		const message = is_tag_valid_with_parent('#text', context.state.parent_element);
 		if (message) {
 			e.node_invalid_placement(node, message);

packages/svelte/src/compiler/phases/2-analyze/visitors/HtmlTag.js

@@ -2,12 +2,16 @@
 /** @import { Context } from '../types' */
 import { mark_subtree_dynamic } from './shared/fragment.js';
 import { validate_opening_tag } from './shared/utils.js';
+import * as e from '../../../errors.js';
 
 /**
  * @param {AST.HtmlTag} node
  * @param {Context} context
  */
 export function HtmlTag(node, context) {
+	if (context.state.analysis.custom_renderer) {
+		e.incompatible_with_custom_renderer(node, '`@html`');
+	}
 	if (context.state.analysis.runes) {
 		validate_opening_tag(node, context.state, '@');
 	}

packages/svelte/src/compiler/phases/2-analyze/visitors/OnDirective.js

@@ -1,5 +1,6 @@
 /** @import { AST } from '#compiler' */
 /** @import { Context } from '../types' */
+import * as e from '../../../errors.js';
 import * as w from '../../../warnings.js';
 import { mark_subtree_dynamic } from './shared/fragment.js';
 
@@ -8,6 +9,10 @@ import { mark_subtree_dynamic } from './shared/fragment.js';
  * @param {Context} context
  */
 export function OnDirective(node, context) {
+	if (context.state.analysis.custom_renderer) {
+		e.incompatible_with_custom_renderer(node, '`on:`');
+	}
+
 	if (context.state.analysis.runes) {
 		const parent_type = context.path.at(-1)?.type;
 

packages/svelte/src/compiler/phases/2-analyze/visitors/RegularElement.js

@@ -25,7 +25,10 @@ import { runes } from '../../../state.js';
  */
 export function RegularElement(node, context) {
 	validate_element(node, context);
-	check_element(node, context);
+
+	if (!context.state.analysis.custom_renderer) {
+		check_element(node, context);
+	}
 
 	node.metadata.path = [...context.path];
 	context.state.analysis.elements.push(node);
@@ -34,7 +37,9 @@ export function RegularElement(node, context) {
 	if (node.name === 'textarea' && node.fragment.nodes.length > 0) {
 		for (const attribute of node.attributes) {
 			if (attribute.type === 'Attribute' && attribute.name === 'value') {
-				e.textarea_invalid_content(node);
+				if (!context.state.analysis.custom_renderer) {
+					e.textarea_invalid_content(node);
+				}
 			}
 		}
 
@@ -110,7 +115,10 @@ export function RegularElement(node, context) {
 
 	// Special case: <select>, <option> or <optgroup> with rich content needs special hydration handling
 	// We mark the subtree as dynamic so parent elements properly include the child init code
-	if (is_customizable_select_element(node) || node.name === 'selectedcontent') {
+	if (
+		(is_customizable_select_element(node) || node.name === 'selectedcontent') &&
+		!context.state.analysis.custom_renderer
+	) {
 		// Mark the element's own fragment as dynamic so it's not treated as static
 		node.fragment.metadata.dynamic = true;
 		// Also mark ancestor fragments so parents properly include the child init code
@@ -157,7 +165,7 @@ export function RegularElement(node, context) {
 		mark_subtree_dynamic(context.path);
 	}
 
-	if (context.state.parent_element) {
+	if (context.state.parent_element && !context.state.analysis.custom_renderer) {
 		let past_parent = false;
 		let only_warn = false;
 		const ancestors = [context.state.parent_element];
@@ -218,7 +226,8 @@ export function RegularElement(node, context) {
 		context.state.analysis.source[node.end - 2] === '/' &&
 		!is_void(node_name) &&
 		!is_svg(node_name) &&
-		!is_mathml(node_name)
+		!is_mathml(node_name) &&
+		!context.state.analysis.custom_renderer
 	) {
 		w.element_invalid_self_closing_tag(node, node.name);
 	}

packages/svelte/src/compiler/phases/2-analyze/visitors/SvelteBody.js

@@ -9,6 +9,10 @@ import { disallow_children } from './shared/special-element.js';
  * @param {Context} context
  */
 export function SvelteBody(node, context) {
+	if (context.state.analysis.custom_renderer) {
+		e.incompatible_with_custom_renderer(node, '`<svelte:body>`');
+	}
+
 	disallow_children(node);
 	for (const attribute of node.attributes) {
 		if (

packages/svelte/src/compiler/phases/2-analyze/visitors/SvelteDocument.js

@@ -9,6 +9,10 @@ import { is_event_attribute } from '../../../utils/ast.js';
  * @param {Context} context
  */
 export function SvelteDocument(node, context) {
+	if (context.state.analysis.custom_renderer) {
+		e.incompatible_with_custom_renderer(node, '`<svelte:document>`');
+	}
+
 	disallow_children(node);
 
 	for (const attribute of node.attributes) {

packages/svelte/src/compiler/phases/2-analyze/visitors/SvelteElement.js

@@ -12,7 +12,10 @@ import { mark_subtree_dynamic } from './shared/fragment.js';
  */
 export function SvelteElement(node, context) {
 	validate_element(node, context);
-	check_element(node, context);
+
+	if (!context.state.analysis.custom_renderer) {
+		check_element(node, context);
+	}
 
 	node.metadata.path = [...context.path];
 	context.state.analysis.elements.push(node);