Skip to content

Commit 9991514

Browse files
ryansolidClaude via Cursor
andcommitted
web: dynamicComponent — component-only sibling of dynamic
Ruling (2026-10-07): `dynamic` stays the combo (component or tag name); `dynamicComponent` is the component-only sibling; the server-component docs mount with `dynamicComponent(() => getStory())`. Option (a) of documentation/plans/frames-b3-sync.md §5. `dynamic` is factored into a shared core and the tag arm: `dynamicCore( source, options, tagArm?)` is the whole implementation — the hoisted lazy factory memo (FLIGHT box, never re-runs for a reset), the per-instance value memo (async-memo adoption under hydration, the `latest` token, the `untrack(cached)` warm-up), the three-memo owner shape matching index.server.ts, the render memo's per-site `createSignal(address, { ownedWrite })` + `sites` + `untrack(() => binding.component(props, address))`, kept-resolution delivery (`resolveBinding` / `sameInstance` / `deliveredAddress`), `static: true`. The only thing the arm decides is what a string value renders as: `dynamic` passes `staticElement`, `dynamicComponent` passes nothing. The core never names the element runtime, so a bundle whose only consumer is `dynamicComponent` sheds `staticElement`, `createElement`, `spread`, the prop-collection helpers, the SVG/MathML tables and `getNextElement`. Server twin in index.server.ts, same factoring (the arm is one `ssrElement()`), identical hydration-id consumption: the parity spec renders one page — a client component and a non-live server component reference — through both entry points and asserts the documents are byte-identical (same `_hk` keys, same frame markup, same `_fr` record), inline and streamed; four hydration arms replay the `dynamicComponent` document through each client entry point (adopted, no request, same nodes, both slots live). Type: `dynamicComponent<C extends Component<any>>(source: () => C | Promise<C> | AsyncIterable<C> | null | undefined | false, options?)` — no `string` in the union. A server-component reference has no type-level brand: it is typed as the server function's declared answer, a `Component<P>` (`LiveSource<Component<P>>` for `live`, an intersection that is still one), so `Component<any>` covers it. The type test pins a tag-name source as a compile error here and fine on `dynamic`. Pins: A7 reset/re-ask (9 arms), C16, C17 parametrized over both entry points; every other `dynamic` pin unchanged (shared code). Size (built, vs base d9395e3): page base −7,417 min / −2,152 br → 33,570; page live −7,418 / −2,171 → 37,241; every other scenario 0 / 0. Floors ratcheted to 33.58 / 37.26 KB (measured + 10 B at the 0.01 KB step). The edited-dist model said −2,158 / −2,237 before the source was written. Fixtures (sc-base-app, sc-live-app) and the server-component docs' mount examples switched to `dynamicComponent`; `dynamic`'s docs carry a one-line pointer. Public API: new export `dynamicComponent` on `@solidjs/web` (client and server entries). `dynamic` unchanged. Co-authored-by: Claude via Cursor <[email protected]>
1 parent d9395e3 commit 9991514

25 files changed

Lines changed: 731 additions & 65 deletions
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@solidjs/web": patch
3+
---
4+
5+
Add `dynamicComponent`, the component-only sibling of `dynamic` (client and server entries). Same contract, semantics and hydration shape as `dynamic` — the two share one implementation — but its source type excludes tag names, and it never references the element runtime: `dynamic` must be able to render a tag, so one `dynamic` on a page retains `createElement`, `spread`, the prop-collection helpers and the SVG/MathML tables for everyone; `dynamicComponent` never does. It is the documented way to mount a server component (`dynamicComponent(() => getStory(id))`); a server-component page mounted through it sheds ≈ 2.2 KB brotli. `dynamic` is unchanged.

‎documentation/server-components/server-components-principles.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2156,7 +2156,7 @@ const toggleAll = action(function* (ids: string[], completed: boolean) {
21562156
yield toggleAllTodos(ids, completed);
21572157
});
21582158

2159-
const Todos = dynamic(() => getTodos(filter()));
2159+
const Todos = dynamicComponent(() => getTodos(filter()));
21602160

21612161
<Todos
21622162
row={p => ({ class: { completed: done(p) }, hidden: !!pending.byId[p.id]?.removed })}

‎documentation/server-components/server-components.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -130,22 +130,23 @@ thing here.
130130

131131
## Using it from the client
132132

133-
There is no server-component API on the client. `dynamic` — the same
134-
utility you'd use to swap any component — is the whole surface:
133+
There is no server-component API on the client. `dynamicComponent` — the
134+
component-only form of `dynamic`, the same utility you'd use to swap any
135+
component — is the whole surface:
135136

136137
```tsx
137-
import { dynamic } from "@solidjs/web";
138+
import { dynamicComponent } from "@solidjs/web";
138139

139140
function StoryPage(props) {
140141
const [collapsedAll, setCollapsedAll] = createSignal(false);
141142

142143
// The source is tracked: when props.storyId changes it re-calls the
143144
// server function. Every call for the same (function, args) resolves to
144-
// the IDENTICAL component — a refetch passes dynamic's equals-gate, so
145+
// the IDENTICAL component — a refetch passes the equals-gate, so
145146
// nothing remounts and the stream morphs the boundary in place. A new
146147
// storyId resolves that story's own boundary and the site swaps to it,
147148
// seeded from retained content when the story has shown before.
148-
const Story = dynamic(() => getStory(props.storyId));
149+
const Story = dynamicComponent(() => getStory(props.storyId));
149150

150151
return (
151152
<Story
@@ -223,7 +224,7 @@ own:
223224

224225
- **Wrap the section function in `query`** and route-level `preload` warms
225226
it on intent — the response's chunks buffer until a boundary mounts,
226-
then drain. The `dynamic()` read resolves through the same cached
227+
then drain. The `dynamicComponent()` read resolves through the same cached
227228
in-flight call, and a later fresh cache hit re-materializes the boundary
228229
from retained state with no request at all — back/forward navigation
229230
renders like a bfcache restore.
@@ -365,7 +366,7 @@ must not break:
365366
### What a router does with this
366367

367368
A router integration is thin by design: translate URL changes into
368-
server-function calls and let a `dynamic` source (or
369+
server-function calls and let a `dynamicComponent` source (or
369370
`applyFrameResponse(response, host, { as })` directly) read them — the
370371
router names nothing, because the calls themselves name the boundaries
371372
(invariant 3). Wrapping the section functions in the router's `query`

‎documentation/solid-2.0/03-control-flow.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -228,6 +228,7 @@ const Article = dynamic(() => loadArticle(params.id), { deferStream: true });
228228
#### Notes
229229

230230
- The source evaluation is shared across all mounted instances of the returned component, so using one `dynamic(...)` in many places doesn't duplicate work.
231+
- Because a source may answer with a tag name, one `dynamic` on a page retains the element runtime (`spread`, the attribute helpers, the namespace tables) for everyone; `dynamicComponent(source)` is the same primitive for a source that only ever answers with a component — a server component mount ([RFC 11](11-server-components.md#using-one)) — and never does.
231232

232233
### Client-only components: `clientOnly`
233234

‎documentation/solid-2.0/10-server-functions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -243,7 +243,7 @@ export const feed = live(
243243
);
244244

245245
// client
246-
const Feed = dynamic(() => feed(props.room));
246+
const Feed = dynamicComponent(() => feed(props.room));
247247
```
248248

249249
The client's binding reconnects on death through `live`'s loop; the document render takes first values from the component's sources and hands off (the brand on the component marks the frame's scope); hydration adopts the document's markup and the loop reconnects from there. How frames make the resume _quiet_ — a stable binding identity per address, conditional re-emission by hole — is frames' business, recorded in `documentation/server-components/server-components-principles.md` §9.5. What is RFC-10-level is that liveness has one declaration, one loop, and one status surface across both tiers.

‎documentation/solid-2.0/11-server-components.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
77
## Summary
88

9-
A **server component is a function returned from a server function** — there is no new component API, no new directive, and no `"use client"`. The server function’s _arguments_ are the server’s inputs (ids, filters); the returned component’s _props_ are client positions (**slots**) the server marks but never renders. On the client, `dynamic` is the entire consumption surface: a server-function call that resolves to a frame stream produces a **stable per-call component** — one boundary per (function, arguments), the same per-args rule a query cache keys values by — so refetches of the same call never remount: server content **morphs in place** underneath and client state inside the boundary (focus, inputs, toggles, video) survives server updates. A call with different arguments resolves its own boundary; the site swaps to it, re-materialized instantly from retained state when that call has shown before.
9+
A **server component is a function returned from a server function** — there is no new component API, no new directive, and no `"use client"`. The server function’s _arguments_ are the server’s inputs (ids, filters); the returned component’s _props_ are client positions (**slots**) the server marks but never renders. On the client, `dynamicComponent` — `dynamic`'s component-only form — is the entire consumption surface: a server-function call that resolves to a frame stream produces a **stable per-call component** — one boundary per (function, arguments), the same per-args rule a query cache keys values by — so refetches of the same call never remount: server content **morphs in place** underneath and client state inside the boundary (focus, inputs, toggles, video) survives server updates. A call with different arguments resolves its own boundary; the site swaps to it, re-materialized instantly from retained state when that call has shown before.
1010

1111
The governing invariant is **single-copy**: server content travels as HTML, values the client needs travel as data records, and nothing travels as both. The acceptance test is literal — view-source the page or a navigation response and search for any piece of content; it appears exactly once.
1212

@@ -64,7 +64,7 @@ A complete working setup (no Vite, no metaframework) is `examples/hackernews`; i
6464
## Motivation
6565

6666
- **Islands fall apart on navigation; RSC ships everything twice.** Islands architectures give a lean initial page but degenerate to full-page loads or bespoke protocols when you navigate. RSC-style server components keep rich composition but serialize the rendered tree alongside the HTML — every piece of server content pays twice. This design — _lakes, not islands_ — keeps one copy: the server owns and streams content, the client owns islands of interactivity **inside** it, and neither re-sends what the other has.
67-
- **No new API surface.** Every prior server-components design grew a parallel component model. Here the entire client surface is `dynamic` + server functions (RFC 10) plus one `installServerComponents()` call. Boundary identity is **derived, never declared** — the call’s intrinsic (function, arguments) address keys the boundary, mirroring a data layer’s cache keys by construction, so panes over different calls are independent with nothing annotated and multi-instance mounting fans one stream out to every mounted frame.
67+
- **No new API surface.** Every prior server-components design grew a parallel component model. Here the entire client surface is `dynamicComponent` + server functions (RFC 10) plus one `installServerComponents()` call. Boundary identity is **derived, never declared** — the call’s intrinsic (function, arguments) address keys the boundary, mirroring a data layer’s cache keys by construction, so panes over different calls are independent with nothing annotated and multi-instance mounting fans one stream out to every mounted frame.
6868
- **Client state must survive server updates.** The failure mode that kills server-driven UIs is the refetch that blows away a half-typed reply. Policy here is structural: refetching into the same boundary morphs server content in place; teardown is disposal, never a version bump.
6969

7070
## Detailed design
@@ -102,7 +102,7 @@ async function getStory(id: number) {
102102

103103
```tsx
104104
function StoryPage(props) {
105-
const Story = dynamic(() => getStory(props.storyId));
105+
const Story = dynamicComponent(() => getStory(props.storyId));
106106
return (
107107
<Story comment={p => <CollapsibleComment cid={p.cid}>{p.children}</CollapsibleComment>}>
108108
<ShareBar />
@@ -111,7 +111,9 @@ function StoryPage(props) {
111111
}
112112
```
113113

114-
Navigation is a prop change: the tracked source re-calls the server function. A same-arguments refetch resolves the _same_ component reference (equals-gated — `dynamic` never remounts) and the stream morphs the boundary; a new `storyId` resolves that story’s own boundary and the site swaps to it — instantly, from retained content, when the story has shown before. Client-only state never reaches the server. State _inside_ a boundary belongs to its call (`CollapsibleComment`’s toggles reset per story — story 1’s collapse state never bleeds into story 2), while state _outside_ the boundary (`StoryPage`’s own signals) survives every navigation. First load composes with `<Loading>`; refetches don’t re-fallback.
114+
`dynamicComponent` is `dynamic` for a source that only ever answers with a component ([RFC 03](03-control-flow.md#dynamic-components-the-dynamic-factory)): the same contract and the same implementation, minus the tag arm — `dynamic` has to be able to render a tag name, so one `dynamic` on a page retains the element runtime (`spread` and the attribute helpers) for everyone; a server-component page that mounts with `dynamicComponent` never pays for it.
115+
116+
Navigation is a prop change: the tracked source re-calls the server function. A same-arguments refetch resolves the _same_ component reference (equals-gated — `dynamicComponent` never remounts) and the stream morphs the boundary; a new `storyId` resolves that story’s own boundary and the site swaps to it — instantly, from retained content, when the story has shown before. Client-only state never reaches the server. State _inside_ a boundary belongs to its call (`CollapsibleComment`’s toggles reset per story — story 1’s collapse state never bleeds into story 2), while state _outside_ the boundary (`StoryPage`’s own signals) survives every navigation. First load composes with `<Loading>`; refetches don’t re-fallback.
115117

116118
### What routers get
117119

‎packages/web/src/index.server.ts‎

Lines changed: 34 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,36 @@ export function dynamic<T extends ValidComponent>(
117117
source: () => T | Promise<T> | null | undefined | false,
118118
options?: DynamicOptions
119119
): Component<ComponentProps<T>> {
120+
return dynamicCore(source, options, ssrTag);
121+
}
122+
123+
/**
124+
* The server twin of the client's `dynamicComponent`: `dynamic` for a source
125+
* that only ever answers with a component, never a tag name. Same owner
126+
* shape as `dynamic` on both sides (the factory / value / render memos), so
127+
* hydration ids agree with the client whichever of the two mounts the same
128+
* value. The client entry's JSDoc carries the cost model; here the tag arm
129+
* is simply absent.
130+
*/
131+
export function dynamicComponent<C extends Component<any>>(
132+
source: () => C | Promise<C> | null | undefined | false,
133+
options?: DynamicOptions
134+
): Component<ComponentProps<C>> {
135+
return dynamicCore(source, options);
136+
}
137+
138+
/** `dynamic`'s string arm on the server: a tag name is one `ssrElement()`. */
139+
type TagArm = (tag: string, props: any) => JSX.Element;
140+
const ssrTag: TagArm = (tag, props) =>
141+
ssrElement(tag, props, undefined, true) as unknown as JSX.Element;
142+
143+
// The shared implementation behind `dynamic` and `dynamicComponent`; the tag
144+
// arm is the only thing that differs (what a string value renders as).
145+
function dynamicCore(
146+
source: () => any,
147+
options: DynamicOptions | undefined,
148+
tagArm?: TagArm
149+
): Component<any> {
120150
// Static: the same owner-free path as the client — a tag is one
121151
// ssrElement(), a component one call — so both sides allocate the same
122152
// hydration keys. No memo on either level, so nothing to serialize or hold.
@@ -125,8 +155,7 @@ export function dynamic<T extends ValidComponent>(
125155
if (isDev && component && typeof component.then === "function")
126156
throw new Error("dynamic(): a static source must resolve synchronously, not to a promise");
127157
if (typeof component === "function") return props => (component as Function)(props);
128-
if (typeof component === "string")
129-
return props => ssrElement(component, props, undefined, true) as unknown as JSX.Element;
158+
if (typeof component === "string" && tagArm) return props => tagArm(component, props);
130159
return () => undefined as unknown as JSX.Element;
131160
}
132161
// Mirrors the client exactly — three memos, the same owner shape on both
@@ -238,9 +267,9 @@ export function dynamic<T extends ValidComponent>(
238267
const c: unknown = value();
239268
if (c) {
240269
if (typeof c === "function") return (c as Function)(props);
241-
if (typeof c === "string") {
242-
return ssrElement(c, props, undefined, true) as unknown as JSX.Element;
243-
}
270+
// `dynamic` only: `dynamicComponent` has no tag arm, so a string
271+
// renders nothing there — as it does on the client.
272+
if (typeof c === "string" && tagArm) return tagArm(c, props);
244273
}
245274
},
246275
{ sync: true } as any

‎packages/web/src/index.ts‎

Lines changed: 74 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -332,12 +332,79 @@ export interface DynamicOptions {
332332
* (as a reference) or a serializable value (a tag name). A promise of a
333333
* client component function is a dev error on the server
334334
* (`DYNAMIC_ASYNC_COMPONENT`): resolve the async upstream, or use `lazy()`.
335+
*
336+
* Cost: because a source may answer with a tag name, one `dynamic` on a page
337+
* retains the element runtime (create/claim, `spread`, the namespace tables)
338+
* for everyone. A source that only ever answers with a component — a server
339+
* component mount — should use `dynamicComponent`, which never does.
335340
*/
336341
export function dynamic<T extends ValidComponent>(
337342
source: () => T | Promise<T> | AsyncIterable<T> | null | undefined | false,
338343
options?: DynamicOptions
339344
): Component<ComponentProps<T>> {
340-
if (options?.static) return staticDynamic(untrack(source));
345+
return dynamicCore(source, options, staticElement);
346+
}
347+
348+
/**
349+
* `dynamic` for a source that only ever answers with a component — never a
350+
* tag name. Same contract, same semantics, same hydration shape (the two
351+
* share one implementation): a reactive, optionally async source; a stable
352+
* `Component` back; `{ static: true }` and `{ deferStream: true }` as on
353+
* `dynamic`. The source's type excludes strings, so a tag name is a compile
354+
* error here — use `dynamic` for one.
355+
*
356+
* Cost model, which is the reason this exists: `dynamic` must be able to
357+
* render a tag, so one `dynamic` anywhere on a page retains the element
358+
* runtime — `createElement`, `spread` and the prop-collection helpers, the
359+
* SVG/MathML tables — for everyone, whether or not any source ever answers
360+
* with a string (a bundler cannot know what a source will resolve to).
361+
* `dynamicComponent` has no tag arm and never references that runtime, so a
362+
* page whose only dynamic mounts are components pays nothing for it.
363+
*
364+
* This is the documented way to mount a server component: a server
365+
* function's answer is a component reference, and the frames transport
366+
* resolves every call for the same function to the same mount identity, so
367+
* a refetch or an argument change is delivered into the mounted instance
368+
* rather than remounting it (see `dynamic` for the full account).
369+
*
370+
* @example
371+
* ```tsx
372+
* const Story = dynamicComponent(() => getStory(props.storyId));
373+
* return <Story comment={p => <Comment cid={p.cid}>{p.children}</Comment>} />;
374+
*
375+
* // A client component chosen by (sync) data — the same thing `dynamic`
376+
* // does, without retaining the element runtime for the page.
377+
* const Page = dynamicComponent(() => (page().editable ? Editor : Viewer));
378+
* ```
379+
*/
380+
export function dynamicComponent<C extends Component<any>>(
381+
source: () => C | Promise<C> | AsyncIterable<C> | null | undefined | false,
382+
options?: DynamicOptions
383+
): Component<ComponentProps<C>> {
384+
return dynamicCore(source, options);
385+
}
386+
387+
/**
388+
* How a tag name a source resolved to becomes an element — `dynamic`'s
389+
* string arm (`staticElement`: create or claim, spread, replay hydration
390+
* events). The core takes it as a PARAMETER so that it never names the
391+
* element runtime itself: `dynamic` passes it, `dynamicComponent` passes
392+
* nothing, and a bundle whose only consumer is `dynamicComponent` sheds
393+
* `staticElement` and everything under it.
394+
*/
395+
type TagArm = (tag: string, props: any) => JSX.Element;
396+
397+
// The shared implementation behind `dynamic` and `dynamicComponent`. Every
398+
// line here is load-bearing for both (the pins listed in
399+
// documentation/plans/frames-b3-sync.md §3): the factory/value/render memo
400+
// shape, the FLIGHT box, kept-resolution delivery, the live address accessor.
401+
// The only thing the tag arm decides is what a string value renders as.
402+
function dynamicCore(
403+
source: () => any,
404+
options: DynamicOptions | undefined,
405+
tagArm?: TagArm
406+
): Component<any> {
407+
if (options?.static) return staticDynamic(untrack(source), tagArm);
341408
// `prev` threads into the resolution so a source switching server-component
342409
// calls of the same function DELIVERS instead of swapping: the memo keeps
343410
// its previous value (the mount below never re-renders) and the new call's
@@ -499,7 +566,10 @@ export function dynamic<T extends ValidComponent>(
499566
}
500567

501568
case "string":
502-
return staticElement(component, props);
569+
// `dynamic` only: `dynamicComponent` has no tag arm (its source
570+
// type excludes strings), so a string there renders nothing, like
571+
// any other non-component value.
572+
return tagArm ? tagArm(component, props) : undefined;
503573

504574
default:
505575
break;
@@ -512,7 +582,7 @@ export function dynamic<T extends ValidComponent>(
512582
// memo, no per-instance memo — the instance IS the element or the component
513583
// call, owner-free like compiled JSX, so the server's static path (the same
514584
// rule) produces the same hydration keys.
515-
function staticDynamic(component: any): Component<any> {
585+
function staticDynamic(component: any, tagArm?: TagArm): Component<any> {
516586
if (isDev && component && typeof component.then === "function")
517587
throw new Error("dynamic(): a static source must resolve synchronously, not to a promise");
518588
if (typeof component === "function") {
@@ -526,7 +596,7 @@ function staticDynamic(component: any): Component<any> {
526596
}
527597
return props => untrack(() => component(props));
528598
}
529-
if (typeof component === "string") return props => staticElement(component, props);
599+
if (typeof component === "string" && tagArm) return props => tagArm(component, props);
530600
return () => undefined as unknown as JSX.Element;
531601
}
532602

0 commit comments

Comments
 (0)