0
Fork 0
mirror of https://github.com/TanStack/router.git synced 2026-11-16 19:38:07 +00:00
router/RFC-solid-native-ssr.md
Ryan Carniato b445b89281
feat(solid-router): native SSR match transfer, hydration-claiming boot, provider-owned dispatch (#8213)
* refactor(solid): retire solid-router-ssr-query — Solid's native channels carry the Router + Query pairing

solid-query v6's QueryClientProvider serializes the request's cache into
Solid's hydration registry during SSR and primes the client cache from
it, so running the ssr-query transport alongside it ships every query
payload twice. The package's two runtime conveniences are each a few
lines of userland composition on public APIs: the provider wrap via the
router's Wrap option, and cache-driven redirect() errors handed to
router.navigate from the caches' config.onError.

Converts the three Solid Start e2e apps to the composition (all suites
green, including the redirect-from-query tests) and marks the package
deprecated for the v2 line.

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore: changeset for the solid-router-ssr-query deprecation notice

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(solid-start): named single-flight source for router flight data

Solid's single-flight channel is becoming multi-source (solidjs/solid
653dd41e): mutation responses carry a keyed envelope of per-cache
slices, each routed to the consumer subscribed under its source id.
Today Start claims the single unnamed slot on both halves, which means
any other cache wanting mutation-response data (e.g. solid-query, whose
provider subscribes under "sq" in TanStack/query#11326) displaces the
router's — whichever registers last wins, silently.

The router's flight data now rides its own source id ("tsr"): the
server collector registers additively with registerFlightDataSource and
the client subscribes its consumer under the same id, so router
loader/match state and other caches' slices coexist on one round trip.
A user-supplied collectFlightData hook keeps the unnamed slot to itself,
adding data alongside the router's instead of displacing it.

Both halves feature-detect the protocol on the installed @solidjs/web
(it ships in the release after 2.0.0-rc.4) and fall back to the exact
previous unnamed-slot behavior on older versions; since client and
server resolve the same install, the halves cannot disagree.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(solid-router): loadFlightTarget, the cache-agnostic single-flight trigger

The router's half of flight collection as a public primitive: derive the
flight request for the mutation's target, run the matched routes' data
functions, hand the loaded router to the caller's collect() — any cache
(the router's own state, a query client) composes its extraction on top.
Start's collector now consumes it; errors are contained per Solid
Router's collector convention (flight data is an optimization, never a
mutation error).

Co-authored-by: Cursor <cursoragent@cursor.com>

* refactor(solid-start): require named flight sources, drop the pre-rc.5 fallback

@solidjs/web 2.0.0-rc.5 ships the multi-source single-flight protocol, so
the feature detection and cast shims bridging unreleased types come out:
the client subscribes directly under SOLID_START_FLIGHT_SOURCE, the server
registers its collector via registerFlightDataSource unconditionally (the
unnamed collectFlightData slot now always belongs to the user), and the
@solidjs/web peer floor moves to rc.5.

Co-authored-by: Cursor <cursoragent@cursor.com>

* test(e2e): expect the named single-flight source header

With the pre-rc.5 fallback stripped, the client advertises its named
source and the server echoes what it folded: X-Single-Flight is "tsr" on
both sides, not the legacy "true".

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore(solid): bump solid-js, @solidjs/web, @solidjs/signals to 2.0.0-rc.6

Repo-wide (packages, examples, e2e apps, benchmarks) — a scoped bump
leaves the workspace mixed, and examples/benchmarks then build workspace
solid-start dists (which import registerFlightDataSource, rc.5+) against
their own @solidjs/web rc.4 resolution. rc.6 ships the named flight-data
source API this branch requires plus the settle-walk fix that unblocks
the Solid Query pairing. @tanstack/solid-start's peer floor moves to
rc.6.

The SSR bench helpers move onto rc.6's wire shape: scripted callers use
the data address (`<endpoint>/data/<id>`) — the bare address now answers
document traffic with the no-JS convention.

Co-authored-by: Cursor <cursoragent@cursor.com>

* spike(solid-router): Phase 1 — registry match transfer + hydration-claiming boot

Proves the RFC's Phase 1 claims on the external-SSR harness, against
published core (web 2.0.0-rc.5):

- Server render serializes each match's loaderData/status into Solid's
  hydration registry, content-addressed (`tsr:<matchId>`), the identical
  mechanism solid-query v6 ships queries through — no `__TSR_SSR__`
  script channel.
- The client boot matches synchronously, primes match state from the
  registry (populated at document parse), and commits — no
  `router.load()` before hydrate, loaders do not re-run (0 client runs),
  hydration claims the server DOM identically, and post-hydration
  navigation with an unresolved chunk still shows pending UI and settles
  under its boundary.

Spike-level notes: the commit must happen before hydrate() (store writes
inside the hydration render are owned-scope writes), the transfer covers
settled matches (promise-valued entries for pending loaders are the same
serialize call, next step), and the serialization-context guard keys on
`ctx.serialize` presence (`ctx.async` is not set under this web
version's renderToString).

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(solid-router): native SSR match transfer + hydration-claiming boot (Phase 1)

Grows the spike into the adapter. RouterProvider serializes each settled
match's state (loaderData, status, error, notFound, beforeLoadContext,
ssr) into Solid's hydration registry during server render —
content-addressed (`tsr:<matchId>`), the same channel solid-query v6
ships queries through, no `__TSR_SSR__` script injection. The Router
constructor owns the client half: when the registry holds entries for the
synchronously matched routes, it primes and commits match state at
creation — always outside a render, after the document (and therefore the
entries) parsed, before hydrate(). No load pass before hydration, no
loader re-runs; route chunks resolve at the read point under the
boundaries the server rendered.

Both halves are inert outside the bare pairing: the server skips when
`router.serverSsr` marks the Start contract, and the boot falls through
on the first missing entry (SPA pages, Start's own channel).

Placement is load-bearing: committing inside the hydration render — even
with writes moved off the owner — leaves the claiming walk's registry
bookkeeping desynced (nodes reuse correctly but audit as unclaimed).
Router creation is the client's natural pre-render moment, and the
harness A/B proved it clean.

Validated: external-SSR harness green end to end (registry primed, zero
client loader runs, identical DOM claimed, pending UI on post-hydration
nav), solid-router unit suite 865 tests green, and all 37 Solid Start e2e
tests green against the rc.6-candidate core (workspace tarballs) with the
named-source strips in place. The harness now contains zero transfer
code. Pending matches are skipped, not deferred — promise-valued entries
(streaming SSR) are the next increment.

Co-authored-by: Cursor <cursoragent@cursor.com>

* docs(rfc): record Phase 1 landed state — transfer + boot in the adapter, boundary bullet corrected

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(solid-router): provider-owned server dispatch + streamed loaderData

RouterProvider now owns router.load() on the server, parking the render
on it through an async memo — no more explicit await router.load() in
entries; blocking semantics ride Solid's async SSR. The bare-pairing
harness moves to renderToStream and proves deferred loaderData promises
stream natively (fallback in the shell chunk, value in a later chunk,
settled through hydration without <Await>).

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore: changeset for Phase 1 native SSR transfer

Co-authored-by: Cursor <cursoragent@cursor.com>

* ci: apply automated fixes

* fix(solid): unbreak CI after the solid-js rc.6 bump

Two things were failing the Test job:

- @tanstack/solid-router test:eslint: the repro-external-ssr harness
  is not part of the package tsconfig, so the typed parser rejected
  its .tsx files. Ignore the harness in the package eslint config; it
  is a standalone vite script, not shipped code.

- Four example builds (basic-solid-query, basic-solid-query-file-based,
  kitchen-sink-file-based, kitchen-sink-solid-query) run tsc, and the
  rc.6 types no longer accept the one-argument createEffect form.
  Convert the eleven call sites to the two-argument
  createEffect(source, effect) form already used by the sibling
  examples and e2e apps.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Brenley Dueck <brenleydueck@gmail.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-02 18:50:29 -05:00

7.3 KiB

RFC: Solid-native SSR/hydration for @tanstack/solid-router

Status: draft for discussion Scope: the Solid adapter's SSR transfer and hydration boot — not the cross-framework router API

Context

The Solid v2 line has been converging on a pattern, one PR at a time: every mechanism the router carried for moving state across the wire has a Solid 2.0 channel that does it natively, and every replacement so far has shrunk code and payload while keeping every e2e suite green.

  • SSR query transfer → the hydration registry, content-addressed (solid-query v6; solid-router-ssr-query retired in #8193, which removed a double-ship of every query payload)
  • Post-mutation data → the multi-source single-flight envelope (#8192: named sources + loadFlightTarget)
  • Redirects from cache-driven fetches → a dozen lines composing isRedirect/resolveRedirect with the caches' config.onError
  • The reference for all of it: solidjs/templates fullstack-tanstack (bare vite + Router + Query, no Start, no integration package — templates#287)

What remains are the deeper assumptions, inherited from the React integration model where the framework has no serialization channel and no hydration-claiming, so the router had to build both:

  1. The router owns the SSR envelope. router.serverSsr, the dehydrate()/hydrate() options, and the __TSR_SSR__ script protocol form a parallel serialization channel through the router's own stream injection.
  2. The router loads before hydration. The client is expected to resolve and commit matches before first render (the template's bootLoad, plus the prefetch-pausing it drags along) because React hydration can't claim through async work.
  3. The router owns the HTML's boundary structure. A global catch boundary is injected client-side that the server never rendered — correct when TanStack's stream handlers produce the HTML, a hydration mismatch when Solid's renderer does (today's escape hatch: disableGlobalCatchBoundary: true).
  4. Suspense-era data ergonomics. Deferred/Await patterns exist because components couldn't just read async values. In Solid 2 they can; the idiomatic usage is already "loaders as non-blocking prefetch hints, suspension at the read point."

Principles

  • The framework channel is the transfer. Anything Solid can serialize through the hydration registry (promise-valued, streamed by seroval as it settles) should not ride a router-owned side channel.
  • Never block up front. No pre-hydration load pass, no up-front chunk resolution, no envelope waiting. Solid's lazy already participates in hydration — a route chunk resolves under its boundary and claims its markup when it lands — so route.lazy maps onto read-point resolution. The same goes for data: pending loaders transfer as promises and settle where they're read.
  • Loader API semantics are untouched. Blocking loaders, pendingComponent, beforeLoad, deferred — the cross-framework contract stays. This RFC changes how the adapter transfers and boots, not what the API promises.
  • Data lives in caches that know how to transfer themselves. The router transfers its state (matches, loaderData, statuses); query caches transfer theirs; the flight envelope keys them independently. Nothing aggregates someone else's state.

Phase 1 — the bare pairing goes fully native (no Start exposure)

The template path (createRouter + RouterProvider under Solid's renderer) never enters createStartHandler, so it can change freely.

  • Registry match transfer. (Landed: registryTransfer.ts, serialization in RouterProvider.) During server render the adapter serializes each settled match's state content-addressed (tsr:<matchId> keys) — the pattern solid-query's provider proved. Still open within this bullet: promise-valued entries for matches pending at render time (streaming SSR). This core has no per-match settle promise, so it needs a dispatch-time hook; today pending matches are skipped and the client boot falls through to current behavior.
  • Hydration-claiming boot. (Landed: the Router constructor.) Match synchronously, prime match state from the registry, commit without running loaders. Placement discovered to be load-bearing: committing inside the hydration render desyncs the claiming walk's registry bookkeeping even with writes moved off the owner — router creation is the client's natural pre-render moment (after document parse, before hydrate()). Route chunks resolve at the read point via Solid lazy semantics. This deleted the template's bootLoad (and its URL-divergence reload guard) and the prefetch-pausing flag outright — verified on the production template: zero server-function requests at boot, hydration clean, single-flight unchanged.
  • Boundary parity. (Already true on this line.) The adapter's boundary structure is symmetric between server and client (_resolveMatchesLoadingBoundary consults no hydration state), so disableGlobalCatchBoundary is no longer a parity workaround — it survives as a semantic choice: let errors (including SSR-thrown redirect()) bubble past the router to app-owned boundaries and the stream handler. The template's comment was corrected to say so.

Phase 2 — Start rides it behind the existing contract

start-server-core orchestrates through attachRouterServerSsrUtils, dehydrate()/hydrate(), and the stream handler — that contract is shared core and stays intact as a facade. Within it, the Solid defaultStreamHandler/renderRouterToStream source the transfer from the registry channel instead of __TSR_SSR__ script injection wherever both exist; user dehydrate/hydrate hooks keep working. The flight collector already went through this door: loadFlightTarget absorbed the event-derivation half, and its extraction half shrinks further once match state is registry-addressed.

Regression gate: the three Solid Start e2e suites (basic-solid-query, server-functions, server-routes — 37 tests, including redirect-from-query on both mount and SSR paths, and the transition semantics) all run locally today and define "didn't break Start."

Phase 3 — upstream

Once both runs are proven, propose the defaults upstream with working code and measured deltas (payload double-ship eliminated, boot code deleted, boundary workaround gone), the same argument shape as #8193 one layer deeper. React/Vue adapters are untouched throughout; router-ssr-query-core's transport remains correct for frameworks without a native channel.

Open questions

  • Match key identity: route id + params hash vs match id — needs to be stable across server/client and across redirects into the same route.
  • loaderData streaming semantics vs the existing deferred API: a promise-valued registry entry makes deferred transfer free, but the read-side API compatibility needs mapping.
  • Scroll restoration and __TSR_SSR__ consumers beyond match state (manifest/asset injection) — inventory what else rides the script channel before swapping it.
  • Where the SSR teardown lands for router state (the query cache got cancel+clear on render disposal; matches may want the same).