From 8cc18edbcb2354d91340579fd8f378d21e2e737d Mon Sep 17 00:00:00 2001 From: Janani-bn Date: Thu, 12 Nov 2026 11:20:38 +0530 Subject: [PATCH] Document the universal createRenderer API --- .../reference/rendering/create-renderer.mdx | 168 ++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 src/routes/reference/rendering/create-renderer.mdx diff --git a/src/routes/reference/rendering/create-renderer.mdx b/src/routes/reference/rendering/create-renderer.mdx new file mode 100644 index 0000000000..4fbfeda581 --- /dev/null +++ b/src/routes/reference/rendering/create-renderer.mdx @@ -0,0 +1,168 @@ +--- +title: createRenderer +category: Rendering +use_cases: >- + custom rendering targets, native and canvas renderers, non-DOM rendering, + rendering Solid to a platform-specific tree +tags: + - rendering + - universal + - custom-renderer + - platform + - jsx +version: "1.0" +description: >- + Create the runtime methods Solid needs to render JSX into a custom host tree. +--- + +`createRenderer` builds a Solid renderer for a host other than the browser DOM. A custom renderer supplies the operations for creating, updating, inserting, and removing its nodes. It can be used for targets such as a native UI, canvas, or terminal. + +## Import + +```ts +import { createRenderer } from "solid-js/universal"; +``` + +The JSX compiler must also generate universal output and import its runtime from the module that exports the renderer. For example, configure `babel-preset-solid` with `generate: "universal"` and set `moduleName` to your renderer package. Without this compiler configuration, JSX is compiled for the DOM runtime instead. + +## Type + +```ts +interface RendererOptions { + createElement(tag: string): NodeType; + createTextNode(value: string): NodeType; + replaceText(textNode: NodeType, value: string): void; + isTextNode(node: NodeType): boolean; + setProperty(node: NodeType, name: string, value: T, prev?: T): void; + insertNode(parent: NodeType, node: NodeType, anchor?: NodeType): void; + removeNode(parent: NodeType, node: NodeType): void; + getParentNode(node: NodeType): NodeType | undefined; + getFirstChild(node: NodeType): NodeType | undefined; + getNextSibling(node: NodeType): NodeType | undefined; +} + +function createRenderer( + options: RendererOptions +): Renderer; +``` + +`Renderer` is the object returned by `createRenderer`. It includes the host operations and the runtime helpers used by code compiled in universal mode: `render`, `effect`, `memo`, `createComponent`, `insert`, `spread`, `setProp`, `mergeProps`, and `use`. + +## Parameters + +### `options` + +An object implementing `RendererOptions`. `NodeType` is the type your host uses for both elements and text nodes. + +| Option | Description | +| -------------------------------------- | ---------------------------------------------------------------------------------------- | +| `createElement(tag)` | Create a host element for the supplied tag name. | +| `createTextNode(value)` | Create a text node with the supplied value. | +| `replaceText(node, value)` | Replace the contents of an existing text node. | +| `isTextNode(node)` | Return whether a host node is a text node. | +| `setProperty(node, name, value, prev)` | Apply a JSX property to a host node. `prev` is the previous value when one is available. | +| `insertNode(parent, node, anchor)` | Insert a node before `anchor`; when `anchor` is omitted, append it. | +| `removeNode(parent, node)` | Remove a child node from its parent. | +| `getParentNode(node)` | Return the node's parent, or `undefined` when it has none. | +| `getFirstChild(node)` | Return the node's first child, or `undefined` when it has none. | +| `getNextSibling(node)` | Return the node's next sibling, or `undefined` when it has none. | + +The runtime uses these operations to reconcile changing text, arrays, and child nodes. They must describe the same host tree: insertion and removal need to update the relationships returned by the parent, child, and sibling operations. + +## Return value + +A `Renderer` object containing the configured host operations and the functions needed by compiled universal JSX. Its `render(code, node)` method mounts the result of `code` into `node` and returns a function that disposes the reactive root. + +## Examples + +### Create a DOM-backed renderer + +This example adapts DOM nodes to the universal renderer interface. A non-DOM host supplies equivalent operations for its own node types. + +```ts +import { createRenderer } from "solid-js/universal"; + +const properties = new Set(["className", "textContent"]); + +export const { + render, + effect, + memo, + createComponent, + createElement, + createTextNode, + insertNode, + insert, + spread, + setProp, + mergeProps, + use, +} = createRenderer({ + createElement(tag) { + return document.createElement(tag); + }, + createTextNode(value) { + return document.createTextNode(value); + }, + replaceText(node, value) { + node.nodeValue = value; + }, + isTextNode(node) { + return node.nodeType === Node.TEXT_NODE; + }, + setProperty(node, name, value) { + if (name === "style" && typeof value === "object" && value !== null) { + Object.assign((node as HTMLElement).style, value); + } else if (properties.has(name)) { + (node as any)[name] = value; + } else { + (node as Element).setAttribute(name, String(value)); + } + }, + insertNode(parent, node, anchor) { + parent.insertBefore(node, anchor ?? null); + }, + removeNode(parent, node) { + parent.removeChild(node); + }, + getParentNode(node) { + return node.parentNode ?? undefined; + }, + getFirstChild(node) { + return node.firstChild ?? undefined; + }, + getNextSibling(node) { + return node.nextSibling ?? undefined; + }, +}); +``` + +The compiler's universal output imports these named runtime exports from the configured module. The `render` returned above can then mount a component into a host node: + +```tsx +import { render } from "solid-custom-dom"; + +render(() => , mountNode); +``` + +### Forward Solid control-flow components + +If compiled JSX uses Solid's control-flow components, re-export them from the renderer package so the configured universal runtime can resolve them: + +```ts +export { + ErrorBoundary, + For, + Index, + Match, + Show, + Suspense, + SuspenseList, + Switch, +} from "solid-js"; +``` + +## Related + +- [`render`](/reference/rendering/render) +- [`hydrate`](/reference/rendering/hydrate)