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

@@ -201,6 +201,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
 
 ```
@@ -225,6 +231,12 @@ Rest element properties of `$props()` such as `%property%` are readonly
 The `%rune%` rune is only available inside `.svelte` and `.svelte.js/ts` files
 ```
 
+### 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

@@ -617,6 +617,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
 
 ```
@@ -1125,6 +1131,12 @@ A component can only have one `<%name%>` element
 Valid `<svelte:...>` tag names are %list%
 ```
 
+### svelte_options_customrenderer_disabled
+
+```
+`customRenderer` cannot be set in `<svelte:options>` unless the `experimental.customRenderer` compiler option is enabled
+```
+
 ### svelte_options_deprecated_tag
 
 ```

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

@@ -155,6 +155,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
@@ -171,6 +175,10 @@ This can happen if you render a hydratable on the client that was not rendered o
 
 > The `%rune%` rune is only available inside `.svelte` and `.svelte.js/ts` files
 
+## 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

@@ -271,6 +271,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%
@@ -425,6 +429,10 @@ HTML restricts where certain elements can appear. In case of a violation the bro
 
 > Valid `<svelte:...>` tag names are %list%
 
+## svelte_options_customrenderer_disabled
+
+> `customRenderer` cannot be set in `<svelte:options>` unless the `experimental.customRenderer` compiler option is enabled
+
 ## svelte_options_deprecated_tag
 
 > "tag" option is deprecated — use "customElement" instead

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/check-treeshakeability.js

@@ -59,6 +59,7 @@ for (const key in pkg.exports) {
 	if (key === './internal/disclose-version') continue;
 	if (key === './internal/flags/legacy') continue;
 	if (key === './internal/flags/tracing') continue;
+	if (key === './internal/init-operations') continue;
 
 	for (const type of ['browser', 'default']) {
 		if (!pkg.exports[key][type]) continue;

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

@@ -1194,6 +1194,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
@@ -1539,6 +1549,15 @@ export function svelte_meta_invalid_tag(node, list) {
 	e(node, 'svelte_meta_invalid_tag', `Valid \`<svelte:...>\` tag names are ${list}\nhttps://svelte.dev/e/svelte_meta_invalid_tag`);
 }
 
+/**
+ * `customRenderer` cannot be set in `<svelte:options>` unless the `experimental.customRenderer` compiler option is enabled
+ * @param {null | number | NodeLike} node
+ * @returns {never}
+ */
+export function svelte_options_customrenderer_disabled(node) {
+	e(node, 'svelte_options_customrenderer_disabled', `\`customRenderer\` cannot be set in \`<svelte:options>\` unless the \`experimental.customRenderer\` compiler option is enabled\nhttps://svelte.dev/e/svelte_options_customrenderer_disabled`);
+}
+
 /**
  * "tag" option is deprecated — use "customElement" instead
  * @param {null | number | NodeLike} node

packages/svelte/src/compiler/index.js

@@ -10,6 +10,7 @@ import { analyze_component, analyze_module } from './phases/2-analyze/index.js';
 import { transform_component, transform_module } from './phases/3-transform/index.js';
 import { validate_component_options, validate_module_options } from './validate-options.js';
 import * as state from './state.js';
+import * as e from './errors.js';
 export { default as preprocess } from './preprocess/index.js';
 export { print } from './print/index.js';
 
@@ -28,15 +29,49 @@ 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 || {};
+
+	// resolve the per-component custom renderer, taking `<svelte:options customRenderer={...} />`
+	// into account. The normalized option is always a function returning `string | null | undefined`
+	// (see `validate-options.js`). A string opts in to a specific renderer module, `null`
+	// opts out to plain DOM (while keeping the feature enabled) and an absent option inherits whatever
+	// the global option resolves to.
+	let custom_renderer_option = validated.experimental.customRenderer;
+
+	if (custom_renderer !== undefined) {
+		// the feature is a global compiler option — a component can only override the renderer it uses
+		// (or opt out) when `experimental.customRenderer` is enabled. Otherwise nothing pushes a
+		// renderer, so allowing `<svelte:options customRenderer>` would silently do the wrong thing.
+		if (!options.experimental?.customRenderer && parsed.options?.attributes) {
+			for (const attribute of parsed.options.attributes) {
+				if (attribute.name === 'customRenderer') {
+					e.svelte_options_customrenderer_disabled(attribute);
+				}
+			}
+		}
+
+		if (typeof custom_renderer === 'string') {
+			custom_renderer_option = () => custom_renderer;
+		} else if (custom_renderer === null) {
+			custom_renderer_option = () => null;
+		}
+	}
 
 	/** @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,
+			customRenderer: custom_renderer_option
+		}
 	};
 
 	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,26 @@ export default function read_options(node) {
 				e.svelte_options_deprecated_tag(attribute);
 				break; // eslint doesn't know this is unnecessary
 			}
+			case 'customRenderer': {
+				const { value } = attribute;
+				const chunk = Array.isArray(value) ? value[0] : value;
+
+				if (chunk === true || !chunk || (Array.isArray(value) && value.length !== 1)) {
+					e.svelte_options_invalid_attribute_value(attribute, 'a string or null');
+				}
+
+				if (chunk.type === 'Text') {
+					component_options.customRenderer = chunk.data;
+				} else if (
+					chunk.expression?.type === 'Literal' &&
+					(typeof chunk.expression.value === 'string' || chunk.expression.value === null)
+				) {
+					component_options.customRenderer = chunk.expression.value;
+				} else {
+					e.svelte_options_invalid_attribute_value(attribute, 'a string or null');
+				}
+				break;
+			}
 			case 'customElement': {
 				/** @type {AST.SvelteOptions['customElement']} */
 				const ce = {};
@@ -193,6 +213,17 @@ export default function read_options(node) {
 		}
 	}
 
+	if (
+		component_options.css === 'injected' &&
+		typeof component_options.customRenderer === 'string'
+	) {
+		// 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

@@ -470,6 +470,14 @@ 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 });
+
+	// only an actual renderer module (a string) is incompatible with injected css — a `null`
+	// renderer means the component renders to the DOM, which is fine
+	if (css === 'injected' && typeof custom_renderer === 'string') {
+		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;
 
@@ -479,7 +487,8 @@ export function analyze_component(root, source, options) {
 		component_name: name,
 		dev: options.dev,
 		rootDir: options.rootDir,
-		runes
+		runes,
+		custom_renderer: custom_renderer
 	});
 
 	// TODO remove all the ?? stuff, we don't need it now that we're validating the config

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

@@ -1,12 +1,17 @@
 /** @import { Context } from '../types' */
 /** @import { AST } from '#compiler'; */
 import * as e from '../../../errors.js';
+import { custom_renderer } from '../../../state.js';
 
 /**
  * @param {AST.AnimateDirective} node
  * @param {Context} context
  */
 export function AnimateDirective(node, context) {
+	if (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

@@ -2,6 +2,7 @@
 /** @import { Context } from '../types' */
 import { cannot_be_set_statically, can_delegate_event } from '../../../../utils.js';
 import { get_attribute_chunks, is_event_attribute } from '../../../utils/ast.js';
+import { custom_renderer } from '../../../state.js';
 import { mark_subtree_dynamic } from './shared/fragment.js';
 
 /**
@@ -59,8 +60,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 (!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

@@ -12,6 +12,7 @@ import { binding_properties } from '../../bindings.js';
 import fuzzymatch from '../../../utils/fuzzymatch.js';
 import { is_content_editable_binding, is_svg } from '../../../../utils.js';
 import { mark_subtree_dynamic } from './shared/fragment.js';
+import { custom_renderer } from '../../../state.js';
 
 /**
  * @param {AST.BindDirective} node
@@ -27,6 +28,9 @@ export function BindDirective(node, context) {
 		parent?.type === 'SvelteDocument' ||
 		parent?.type === 'SvelteBody'
 	) {
+		if (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)) {