RFC: Static Initialization Props for Universal Renderers

[ryansolid]

Summary

Universal JSX currently creates host elements first and applies all props afterward through setProp.

const el = createElement("box");
setProp(el, "id", "static-id");
effect(() => setProp(el, "border", dynamic()));

For DOM this is usually fine because template cloning gives the DOM renderer a preconfigured node shape. For universal renderers, especially non-DOM renderers like OpenTUI, some host elements need static configuration at construction time or before children are inserted.

This RFC proposes extending universal createElement to receive compile-time-static props:

const el = createElement("box", {
  id: "static-id"
});
effect(() => setProp(el, "border", dynamic()));

Dynamic props continue to use setProp.

Motivation

Issue: ryansolid/dom-expressions#487

OpenTUI's Solid renderer needs access to expected props during element creation. Today, the compiler emits createElement(tag) before any props are known to the renderer. Static props are applied later through setProp, sometimes after child insertion. That makes it difficult for renderers whose child handling, layout, native object creation, or parent-child registration depends on parent configuration.

The DOM renderer already gets an equivalent benefit through static templates: the cloned node is born with its static attributes. Universal renderers do not have that same construction-time configuration channel.

Current Universal Emit

Given:

<box id="static-id" border={dynamic()} />

Universal emit is approximately:

const el = createElement("box");
setProp(el, "id", "static-id");
effect(() => setProp(el, "border", dynamic()));

This means the renderer only sees "box" at construction time.

Proposed Emit

Pass compile-time-static props as the second argument to createElement:

const el = createElement("box", {
  id: "static-id"
});
effect(() => setProp(el, "border", dynamic()));

Update the universal renderer contract to:

createElement(tag: string, props?: Record<string, unknown>): NodeType;

Static props included in this object would no longer be emitted as separate setProp calls.

What Counts as Static

Static means the compiler can emit the value without creating reactive tracking.

Examples:

<box id="main" disabled />
<box textContent="Hello" />
<box style={{ color: "red" }} />

These can be included in the initialization props.

Dynamic expressions continue to use setProp:

<box id={id()} />
<box border={dynamic()} />

The RFC does not propose untracking dynamic props to pass their initial value into createElement. That would call dynamic expressions once during construction and again through the reactive update path, and Solid 2.0's async timing makes this more fragile.

Spreads

Spreads remain runtime-managed:

<box {...props} id="main" />

The compiler cannot generally know spread contents ahead of time. Spreads continue through spread / setProp behavior.

Open question: if static props appear before or after a spread, should any subset still be passed to createElement, or should spread presence force all props through the current path? The conservative first version can avoid passing static props on elements with spreads.

Style and Class

Open question: include static style / class values in the initialization object, or keep them as setProp calls?

Including them is more consistent with "static props at construction." Keeping them separate is safer if renderer authors already rely on specialized setProp handling for style/class normalization.

Alternative: Finalize / Commit Hook

An alternative design is to keep createElement(tag) unchanged and add a hook after static props and children are attached:

const el = createElement("box");
setProp(el, "id", "static-id");
insertNode(el, child);
finalizeElement(el);

This answers a different question: "tell the renderer when this subtree is ready." That may be useful for renderers that want to defer native bridge sync, layout, or parent-child registration until after construction.

However, it is a larger lifecycle addition. The immediate issue is that renderers need parent configuration before child insertion or native object setup. Passing static props to createElement is the smaller change and better matches the DOM renderer's static-template advantage.

Compatibility

This is a breaking universal compiler/runtime contract change.

Renderers currently implement:

createElement(tag: string): NodeType;

They would need to tolerate:

createElement(tag: string, props?: Record<string, unknown>): NodeType;

A renderer can ignore props to preserve existing behavior, but if the compiler stops emitting static setProp calls, ignoring props means static props will not be applied.

Because 0.50 / Solid 2.0 is still in beta, the preferred path is to make this an unconditional universal emit change rather than support two long-term emit modes.

Proposed Resolution

Adopt createElement(tag, staticProps?) for universal renderers.

Do not pass dynamic initial values.

Do not add a subtree commit hook as part of this change, but leave it open for a future RFC if renderer maintainers identify a distinct need for "subtree finished" notification.

Questions for Renderer Maintainers

1. Is construction-time access to compile-time-static props enough for your renderer?
2. Do you need static props before child insertion specifically?
3. Would a later finalizeElement / commitElement hook solve a different problem for your renderer?
4. Should static style and class be included in the construction props object?
5. Should elements with spreads opt out of construction props for the first implementation?

Non-goals

• No JSX syntax changes.
• No DOM renderer emit changes.
• No dynamic initial prop evaluation through untrack.
• No broad lifecycle system for universal renderers in this RFC.

[chiefcll]

https://github.com/solid-tv/solid can adopt the proposed resolution.

We build a full temp object before creating the underlying WebGL object.

Is construction-time access to compile-time-static props enough for your renderer?
Sure.
Do you need static props before child insertion specifically?
Nope
Would a later finalizeElement / commitElement hook solve a different problem for your renderer?
Yes - currently I have a queueMicrotask that runs after elements are inserted.
Should static style and class be included in the construction props object?
N/A
Should elements with spreads opt out of construction props for the first implementation?
N/A

[Adictya]

Hi, thanks for taking this up

--

1. Is construction-time access to compile-time-static props enough for your renderer?

Yes that satisfies the initial requirement in most cases, our idealized version would be behavior parity in this regard between our solid
and react reconcilers as they mirror each other in a lot of ways but its a fair compromise.

--

2. Do you need static props before child insertion specifically?

Not necessarily, maybe purely as a nice to have to track id's for debugging through reconciler operations as we don't have to rely on auto-generated ones.

--

3. Would a later finalizeElement / commitElement hook solve a different problem for your renderer?

Potentially yes in the future as we move dom to native but we could also always do through microstasks so not a hard requirement.

Although I would have guessed this would be able to account for non async dynamic props and get called after all the initial setProp / insert calls, but from your wording it seems like even this wouldn't?

--

4. Should static style and class be included in the construction props object?

Yes

--

5. Should elements with spreads opt out of construction props for the first implementation?

Open question: if static props appear before or after a spread, should any subset still be passed to createElement, or should spread presence force all props through the current path? The conservative first version can avoid passing static props on elements with spreads.

Yes, happy with a conservative first version not passing it, long term given its not a question of runtime complexity and just behavior DX I would lean on having non spread props be passed statically even with a spread present