feat(solid): Solid-owned SSR transport and payload channel

[ryansolid]

Summary

Phase 2 of the Solid-native SSR plan (RFC updated in the diff). Moves the Solid adapter's SSR stream transport and dehydration payload onto Solid's own channels — with zero diff outside the Solid packages. router-core, start-client-core, react-router, vue-router, and their start packages are byte-for-byte untouched:

git diff origin/solid-router-v2-pre..HEAD --stat -- packages
# 12 files changed — all under packages/solid-router and packages/solid-start-client

• Transport (2a) — renderRouterToStream no longer pipes through transformReadableStreamWithRouter (the per-chunk decode + </body> scan + splice transform). Router scripts write directly to the response sink as the serializer emits them; the script barrier lifts once the chunk carrying <Scripts /> has been written (chunks are scanned only until that marker is seen); the response closes when both the render completed and serialization finished, preserving the transform's 60s timeout and abort/cleanup semantics. Zero per-chunk decode/scan/splice on the hot path.
• Payload (2b) — the DehydratedRouter rides Solid's eval-free JSON record codec (the same createJSONSerializer/createJSONDataTable infrastructure Start's server functions use) as __TSR_P queue pushes, instead of the $_TSR script channel. The rendered HTML carries no $_TSR bootstrap, no $R cross-reference header, and no parse-time eval — every router script is an inert JSON data push. This also removes the parse-time wall that blocked registry-addressed transfer: adapter-typed values decode at runtime through makeSerovalPlugin-wrapped adapters rather than evaluating $_TSR.t.get(key)(...) calls before implementations exist.

How it stays out of core

Everything rides Solid-side overrides of the framework-only router.serverSsr members, installed through the existing onServerSsrAttach lifecycle:

• Attach seam — the Solid Router constructor registers an onServerSsrAttach listener that resolves an installer through a slot (solidSsrTransferSlot) filled by the ssr/server entry module. The encode half of Solid's codec is server-only and must never enter the client module graph; the package sideEffects allowlist keeps bundlers from dropping the slot fill. Unfilled slot ⇒ core's script channel runs completely unchanged.
• Server (installSolidSsrTransfer) — replaces serverSsr.dehydrate with a Solid implementation that builds the DehydratedRouter the way core does (rendered matches, isShell slicing, options.dehydrate() data, manifest derived from the public router.ssr.manifest getter) and serializes it through the JSON codec into a Solid-owned script buffer. takeBufferedScripts/liftScriptBarrier are overridden to serve that buffer with core's exact shell-inline tag shape, so <Scripts /> inlining and barrier deferral work unchanged. isDehydrated/isSerializationFinished/onSerializationFinished answer from Solid-side state; setRenderFinished/cleanup wrap the originals. Core's seeded $R header and $_TSR bootstrap are drained and discarded at attach.
• Client (synthetic $_TSR) — core hydrate() is unchanged; it still reads window.$_TSR. Solid installs a synthetic $_TSR whose lazy router getter decodes the __TSR_P queue (push-hooked so late records settle streamed loaderData promises), applied by RouterClient and Solid's hydrateStart. The decode module is loaded through a dynamic import so it shares the chunk Solid's web runtime already lazy-loads (a static import merges it into the client entry chunk, which then registers as a dynamic-import target and loses its isEntry flag to the Solid vite plugin's lazy-entry normalization — breaking Start's manifest capture for apps on the default client entry); the shim's install returns a promise the callers await before core hydrate. The synthetic's h() deletes the global once hydration completes — it has no post-hydration role since late records ride the queue's hooked push, never $_TSR.p — so typeof window.$_TSR === 'undefined' stays a valid hydration-finished probe on both channels (the basic-auth e2e suite relies on it). The shim defers to a real $_TSR bootstrap, so documents rendered by a script-channel server still hydrate.

The unexported core pieces mirrored on the Solid side (dehydrateMatch, ScriptBuffer + barrier tag shape, the inline-CSS placeholder) are marked as mirrors in routerPayloadServer.ts. A follow-up PR against main will add the small core hooks (framework dehydrated-router hand-off, script enqueue, serialization-finished signal) that let these overrides and mirrors collapse into supported seams — this PR deliberately does not depend on it, since core releases on a different cadence than this pre-release branch.

Verification

All on this branch after the rebase onto solid-router-v2-pre (post #8192/#8213 merge):

• @tanstack/solid-router unit tests: 865 passed | 2 skipped across 59 files, zero type errors (jsdom + server-mode + typecheck).
• Bare-pairing harness (packages/solid-router/repro-external-ssr, real server/client bundles, protocol-less SSR → hydration in jsdom): PASS — clean hydration, zero console errors/warnings, no pending flash, post-hydration nav works, streamed loaderData chunk-order assertions hold.
• Ten Solid Start e2e suites, fresh builds: basic (80), server-functions (29), deferred-hydration (15), selective-ssr (11), scroll-restoration (10), basic-auth (7), basic-solid-query (6), serialization-adapters (5), server-routes (2), spa-mode (2) — 167 passed covering streaming order, selective-SSR lanes, adapter decode through the shim, scroll scripts, shell mode, and auth/redirect flows with the hydration-probe semantics.
• Default-entry app builds (the chunk-graph shape the e2e apps' custom entries don't exercise): examples/solid/start-large, examples/solid/start-basic-authjs, and @benchmarks/bundle-size all build clean.
• Rendered-HTML spot check: SSR output carries __TSR_P records only — zero $_TSR occurrences.

Notes for reviewers

• The serverSsr overrides install at attachRouterServerSsrUtils time via onServerSsrAttach, i.e. before any dehydrate/injection call site can run — but the ordering is implicit. The core-hooks PR will make it explicit.
• Core's internal isDehydrated/serialization flags never advance in this mode (core's dehydrate body never runs); anything inside core that consulted them directly rather than through the serverSsr surface would misread. Nothing does today — flagging it as the kind of coupling the core hooks should eliminate.
• Benchmarks: the SSR scenarios' dehydration-marker detection now accepts either channel's marker ($_TSR or __TSR_P), so CodSpeed stays meaningful across frameworks.
• The decode-chunk hazard above is worth knowing about generally: any package that statically imports @solidjs/web/serialization/decode into a chunk Solid's runtime also dynamically imports will strip the client entry's isEntry under the current vite-plugin normalization. The core-hooks PR won't change this — it's a bundler-graph property — but it's now documented in the RFC.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 5df252e8-6aec-48d3-969d-cabc0c8d101d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 86203b8

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	❌ Failed	7m 2s	View ↗
nx run-many --target=build --exclude=examples/*...	❌ Failed	1m 54s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-09-03 02:52:35 UTC

[codspeed-hq]

Hooray! CodSpeed harness just leveled up!

The base and head of this comparison were measured with different runner settings, so their benchmark values are not directly comparable.

What changed between base and head:

• CodSpeed runner v5 changed how benchmarks are measured (base 4.15.0 → head 5.0.2). View release notes
• Cycle estimation (off → on) changes how benchmark performance is calculated. Learn more about cycle estimation

Re-run the base with the same settings to get a valid performance comparison.

---

_{Comparing ryansolid:feat/solid-ssr-transport-payload (86203b8) with solid-router-v2-pre (67a9040)¹}

Footnotes

1. No successful run was found on solid-router-v2-pre (b445b89) during the generation of this report, so 67a9040 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[brenelz]

Yeah we should see if we can do this without modifying core packages. We don't have good versioning for changes to those right now until we are on the main branch

[ryansolid]

A plain-language summary of what this solves, since the description above is mechanism-heavy.

Some context on how this builds on #8213: before it, the router's SSR story was effectively Start-shaped. The $_TSR script channel and the dehydrate machinery live in Start's request-handler flow, so in bare projects (anyone hosting <RouterProvider> in their own Solid SSR server) there was no state transfer at all — loader data computed on the server evaporated, the client re-ran every loader (double fetch, pending flash), and since the server rendered with resolved matches while the client booted with pending ones, the trees diverged and Solid's hydration claiming broke. #8213 fixed that natively: match state rides Solid's hydration registry (the same seroval channel Solid uses for its own signals, so deferred loaderData promises stream for free), the router's stores are primed from the registry before hydration walks the DOM so every node claims cleanly, and RouterProvider owns router.load() as an async memo, so SSR composes with renderToStream and Loading boundaries instead of requiring an orchestrated await router.load() in the server entry.

This PR completes the same story inside Start, where three pieces of shared-path overhead remain on the Solid adapter:

1. Every SSR response gets re-processed in transit. transformReadableStreamWithRouter decodes each rendered chunk to a string, scans for the injection point, splices scripts, and re-encodes. Solid's renderer already has a native seam for sinking scripts into the stream, so on the Solid path that transform is pure per-chunk overhead. With this PR, router scripts write straight into the response as the serializer emits them.

2. Loader data ships twice, in two encodings. Since feat(solid-router): native SSR match transfer, hydration-claiming boot, provider-owned dispatch #8213, match state rides Solid's hydration registry — but core's dehydrate still serializes the full DehydratedRouter through the $_TSR script channel on top of it. This PR collapses the payload to one channel (Solid's JSON record codec — the same infrastructure Start's server functions on Solid already use), so the data ships once and the client bundles one deserializer instead of two.

3. Hydration stops depending on script eval. The $_TSR channel executes seroval scripts at parse time; the JSON codec is inert data decoded by runtime code that already ships. That's a straight CSP-posture improvement, and it matches how the rest of Solid 2.0 hydration works.

What it costs core: verifiably nothing — the diff is confined to packages/solid-router and packages/solid-start-client, React/Vue are byte-for-byte untouched, and their e2e + CodSpeed runs are green. If this doesn't land, Solid Start keeps working fine on the shared path; it just permanently carries the double transform, the double payload ship, and the eval dependence. The serverSsr overrides are the framework-only surface doing what it exists for — and the planned follow-up PR against main proposes the small hooks that would make these seams first-class, though nothing here depends on it.