* 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>
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-queryv6;solid-router-ssr-queryretired 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/resolveRedirectwith 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:
- The router owns the SSR envelope.
router.serverSsr, thedehydrate()/hydrate()options, and the__TSR_SSR__script protocol form a parallel serialization channel through the router's own stream injection. - 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. - 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). - Suspense-era data ergonomics. Deferred/
Awaitpatterns 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
lazyalready participates in hydration — a route chunk resolves under its boundary and claims its markup when it lands — soroute.lazymaps 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 inRouterProvider.) During server render the adapter serializes each settled match's state content-addressed (tsr:<matchId>keys) — the patternsolid-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
Routerconstructor.) 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, beforehydrate()). Route chunks resolve at the read point via Solidlazysemantics. This deleted the template'sbootLoad(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
(
_resolveMatchesLoadingBoundaryconsults no hydration state), sodisableGlobalCatchBoundaryis no longer a parity workaround — it survives as a semantic choice: let errors (including SSR-thrownredirect()) 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.
loaderDatastreaming 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).