@tanstack/router-core 1.168.9 → 1.168.11

package/src/ssr/serializer/ShallowErrorPlugin.ts

@@ -1,7 +1,7 @@
 import { createPlugin } from 'seroval'
-import type { SerovalNode } from 'seroval'
+import type { PluginInfo, SerovalNode } from 'seroval'
 
-export interface ErrorNode {
+export interface ErrorNode extends PluginInfo {
   message: SerovalNode
 }
 

package/src/ssr/serializer/seroval-plugins.ts

@@ -1,12 +1,13 @@
 import { ReadableStreamPlugin } from 'seroval-plugins/web'
 import { ShallowErrorPlugin } from './ShallowErrorPlugin'
 import { RawStreamSSRPlugin } from './RawStream'
+import type { RawStream } from './RawStream'
 import type { Plugin } from 'seroval'
 
 export const defaultSerovalPlugins = [
   ShallowErrorPlugin as Plugin<Error, any>,
   // RawStreamSSRPlugin must come before ReadableStreamPlugin to match first
-  RawStreamSSRPlugin,
+  RawStreamSSRPlugin as Plugin<RawStream, any>,
   // ReadableStreamNode is not exported by seroval
   ReadableStreamPlugin as Plugin<ReadableStream, any>,
 ]

package/src/ssr/serializer/transformer.ts

@@ -1,6 +1,6 @@
 import { createPlugin } from 'seroval'
 import { GLOBAL_TSR } from '../constants'
-import type { Plugin, SerovalNode } from 'seroval'
+import type { Plugin, PluginInfo, SerovalNode } from 'seroval'
 import type {
   RegisteredConfigType,
   RegisteredSsr,
@@ -14,6 +14,7 @@ declare const TSR_SERIALIZABLE: unique symbol
 export type TSR_SERIALIZABLE = typeof TSR_SERIALIZABLE
 
 export type TsrSerializable = { [TSR_SERIALIZABLE]: true }
+
 export interface DefaultSerializable {
   number: number
   string: string
@@ -25,6 +26,7 @@ export interface DefaultSerializable {
   Uint8Array: Uint8Array
   RawStream: RawStream
   TsrSerializable: TsrSerializable
+  void: void
 }
 
 export interface SerializableExtensions extends DefaultSerializable {}
@@ -72,13 +74,14 @@ export interface CreateSerializationAdapterOptions<
   fromSerializable: (value: TOutput) => TInput
 }
 
-export type ValidateSerializable<T, TSerializable> =
-  T extends ReadonlyArray<unknown>
-    ? ResolveArrayShape<T, TSerializable, 'input'>
-    : T extends TSerializable
-      ? T
-      : T extends (...args: Array<any>) => any
-        ? 'Function is not serializable'
+export type ValidateSerializable<T, TSerializable> = T extends TSerializable
+  ? T
+  : T extends (...args: Array<any>) => any
+    ? SerializationError<'Function may not be serializable'>
+    : T extends RegisteredReadableStream
+      ? SerializationError<'JSX is not be serializable'>
+      : T extends ReadonlyArray<any>
+        ? ValidateSerializableArray<T, TSerializable>
         : T extends Promise<any>
           ? ValidateSerializablePromise<T, TSerializable>
           : T extends ReadableStream<any>
@@ -89,9 +92,9 @@ export type ValidateSerializable<T, TSerializable> =
                 ? ValidateSerializableMap<T, TSerializable>
                 : T extends AsyncGenerator<any, any>
                   ? ValidateSerializableAsyncGenerator<T, TSerializable>
-                  : {
-                      [K in keyof T]: ValidateSerializable<T[K], TSerializable>
-                    }
+                  : T extends object
+                    ? ValidateSerializableMapped<T, TSerializable>
+                    : SerializationError<'Type may not be serializable'>
 
 export type ValidateSerializableAsyncGenerator<T, TSerializable> =
   T extends AsyncGenerator<infer T, infer TReturn, infer TNext>
@@ -125,16 +128,26 @@ export type ValidateSerializableMap<T, TSerializable> =
       >
     : never
 
-export type RegisteredReadableStream =
-  unknown extends SerializerExtensions['ReadableStream']
-    ? never
-    : SerializerExtensions['ReadableStream']
+export type ValidateSerializableArray<T, TSerializable> = T extends readonly [
+  any,
+  ...Array<any>,
+]
+  ? ValidateSerializableMapped<T, TSerializable>
+  : T extends Array<infer U>
+    ? Array<ValidateSerializable<U, TSerializable>>
+    : T extends ReadonlyArray<infer U>
+      ? ReadonlyArray<ValidateSerializable<U, TSerializable>>
+      : never
 
-export interface DefaultSerializerExtensions {
-  ReadableStream: unknown
+export type ValidateSerializableMapped<T, TSerializable> = {
+  [K in keyof T]: ValidateSerializable<T[K], TSerializable>
 }
 
-export interface SerializerExtensions extends DefaultSerializerExtensions {}
+const SERIALIZATION_ERROR = Symbol.for('TSR_SERIALIZATION_ERROR')
+
+export interface SerializationError<in out TMessage extends string> {
+  [SERIALIZATION_ERROR]: TMessage
+}
 
 export interface SerializationAdapter<
   TInput,
@@ -161,27 +174,34 @@ export interface SerializationAdapterTypes<
 
 export type AnySerializationAdapter = SerializationAdapter<any, any, any>
 
+export interface AdapterNode extends PluginInfo {
+  v: SerovalNode
+}
+
 /** Create a Seroval plugin for server-side serialization only. */
+/* @__NO_SIDE_EFFECTS__ */
 export function makeSsrSerovalPlugin(
   serializationAdapter: AnySerializationAdapter,
   options: { didRun: boolean },
-): Plugin<any, SerovalNode> {
-  return createPlugin<any, SerovalNode>({
+): Plugin<any, AdapterNode> {
+  return /* @__PURE__ */ createPlugin<any, AdapterNode>({
     tag: '$TSR/t/' + serializationAdapter.key,
     test: serializationAdapter.test,
     parse: {
-      stream(value, ctx) {
-        return ctx.parse(serializationAdapter.toSerializable(value))
+      stream(value, ctx, _data) {
+        return {
+          v: ctx.parse(serializationAdapter.toSerializable(value)),
+        }
       },
     },
-    serialize(node, ctx) {
+    serialize(node, ctx, _data) {
       options.didRun = true
       return (
         GLOBAL_TSR +
         '.t.get("' +
         serializationAdapter.key +
         '")(' +
-        ctx.serialize(node) +
+        ctx.serialize(node.v) +
         ')'
       )
     },
@@ -191,27 +211,34 @@ export function makeSsrSerovalPlugin(
 }
 
 /** Create a Seroval plugin for client/server symmetric (de)serialization. */
+/* @__NO_SIDE_EFFECTS__ */
 export function makeSerovalPlugin(
   serializationAdapter: AnySerializationAdapter,
-): Plugin<any, SerovalNode> {
-  return createPlugin<any, SerovalNode>({
+): Plugin<any, AdapterNode> {
+  return /* @__PURE__ */ createPlugin<any, AdapterNode>({
     tag: '$TSR/t/' + serializationAdapter.key,
     test: serializationAdapter.test,
     parse: {
-      sync(value, ctx) {
-        return ctx.parse(serializationAdapter.toSerializable(value))
+      sync(value, ctx, _data) {
+        return {
+          v: ctx.parse(serializationAdapter.toSerializable(value)),
+        }
       },
-      async async(value, ctx) {
-        return await ctx.parse(serializationAdapter.toSerializable(value))
+      async async(value, ctx, _data) {
+        return {
+          v: await ctx.parse(serializationAdapter.toSerializable(value)),
+        }
       },
-      stream(value, ctx) {
-        return ctx.parse(serializationAdapter.toSerializable(value))
+      stream(value, ctx, _data) {
+        return {
+          v: ctx.parse(serializationAdapter.toSerializable(value)),
+        }
       },
     },
     // we don't generate JS code outside of SSR (for now)
     serialize: undefined as never,
-    deserialize(node, ctx) {
-      return serializationAdapter.fromSerializable(ctx.deserialize(node))
+    deserialize(node, ctx, _data) {
+      return serializationAdapter.fromSerializable(ctx.deserialize(node.v))
     },
   })
 }
@@ -234,20 +261,6 @@ export type RegisteredSerializationAdapters<TRegister> = RegisteredConfigType<
   'serializationAdapters'
 >
 
-export type ValidateSerializableInputResult<TRegister, T> =
-  ValidateSerializableResult<T, RegisteredSerializableInput<TRegister>>
-
-export type ValidateSerializableResult<T, TSerializable> =
-  T extends ReadonlyArray<unknown>
-    ? ResolveArrayShape<T, TSerializable, 'result'>
-    : T extends TSerializable
-      ? T
-      : unknown extends SerializerExtensions['ReadableStream']
-        ? { [K in keyof T]: ValidateSerializableResult<T[K], TSerializable> }
-        : T extends SerializerExtensions['ReadableStream']
-          ? ReadableStream
-          : { [K in keyof T]: ValidateSerializableResult<T[K], TSerializable> }
-
 export type RegisteredSSROption<TRegister> =
   unknown extends RegisteredConfigType<TRegister, 'defaultSsr'>
     ? SSROption
@@ -282,31 +295,13 @@ export type ValidateSerializableLifecycleResultSSR<
       ? any
       : ValidateSerializableInput<TRegister, LooseReturnType<TFn>>
 
-type ResolveArrayShape<
-  T extends ReadonlyArray<unknown>,
-  TSerializable,
-  TMode extends 'input' | 'result',
-> = number extends T['length']
-  ? T extends Array<infer U>
-    ? Array<ArrayModeResult<TMode, U, TSerializable>>
-    : ReadonlyArray<ArrayModeResult<TMode, T[number], TSerializable>>
-  : ResolveTupleShape<T, TSerializable, TMode>
-
-type ResolveTupleShape<
-  T extends ReadonlyArray<unknown>,
-  TSerializable,
-  TMode extends 'input' | 'result',
-> = T extends readonly [infer THead, ...infer TTail]
-  ? readonly [
-      ArrayModeResult<TMode, THead, TSerializable>,
-      ...ResolveTupleShape<Readonly<TTail>, TSerializable, TMode>,
-    ]
-  : T
-
-type ArrayModeResult<
-  TMode extends 'input' | 'result',
-  TValue,
-  TSerializable,
-> = TMode extends 'input'
-  ? ValidateSerializable<TValue, TSerializable>
-  : ValidateSerializableResult<TValue, TSerializable>
+export type RegisteredReadableStream =
+  unknown extends SerializerExtensions['ReadableStream']
+    ? never
+    : SerializerExtensions['ReadableStream']
+
+export interface DefaultSerializerExtensions {
+  ReadableStream: unknown
+}
+
+export interface SerializerExtensions extends DefaultSerializerExtensions {}

package/src/ssr/ssr-client.ts

@@ -95,7 +95,7 @@ export async function hydrate(router: AnyRouter): Promise<any> {
   }
 
   // Hydrate the router state
-  const matches = router.matchRoutes(router.stores.location.state)
+  const matches = router.matchRoutes(router.stores.location.get())
 
   // kick off loading the route chunks
   const routeChunkPromise = Promise.all(
@@ -162,7 +162,7 @@ export async function hydrate(router: AnyRouter): Promise<any> {
     }
   })
 
-  router.stores.setActiveMatches(matches)
+  router.stores.setMatches(matches)
 
   // Allow the user to handle custom hydration data
   await router.options.hydrate?.(dehydratedData)
@@ -170,8 +170,8 @@ export async function hydrate(router: AnyRouter): Promise<any> {
   // now that all necessary data is hydrated:
   // 1) fully reconstruct the route context
   // 2) execute `head()` and `scripts()` for each match
-  const activeMatches = router.stores.activeMatchesSnapshot.state
-  const location = router.stores.location.state
+  const activeMatches = router.stores.matches.get()
+  const location = router.stores.location.get()
   await Promise.all(
     activeMatches.map(async (match) => {
       try {
@@ -258,7 +258,7 @@ export async function hydrate(router: AnyRouter): Promise<any> {
     // (e.g. preloads, invalidations) don't mistakenly detect a href change
     // (resolvedLocation defaults to undefined and router.load() is skipped
     // in the normal SSR hydration path).
-    router.stores.resolvedLocation.setState(() => router.stores.location.state)
+    router.stores.resolvedLocation.set(router.stores.location.get())
     return routeChunkPromise
   }
 
@@ -292,13 +292,9 @@ export async function hydrate(router: AnyRouter): Promise<any> {
         // ensure router is not in status 'pending' anymore
         // this usually happens in Transitioner but if loading synchronously resolves,
         // Transitioner won't be rendered while loading so it cannot track the change from loading:true to loading:false
-        if (router.stores.status.state === 'pending') {
-          router.batch(() => {
-            router.stores.status.setState(() => 'idle')
-            router.stores.resolvedLocation.setState(
-              () => router.stores.location.state,
-            )
-          })
+        if (router.stores.status.get() === 'pending') {
+          router.stores.status.set('idle')
+          router.stores.resolvedLocation.set(router.stores.location.get())
         }
         // hide the pending component once the load is finished
         router.updateMatch(match.id, (prev) => ({

package/src/ssr/ssr-server.ts

@@ -2,6 +2,7 @@ import { crossSerializeStream, getCrossReferenceHeader } from 'seroval'
 import { invariant } from '../invariant'
 import { decodePath } from '../utils'
 import { createLRUCache } from '../lru-cache'
+import { rootRouteId } from '../root'
 import minifiedTsrBootStrapScript from './tsrScript?script-string'
 import { GLOBAL_TSR, TSR_SCRIPT_BARRIER_ID } from './constants'
 import { dehydrateSsrMatchId } from './ssr-match-id'
@@ -171,12 +172,31 @@ function getManifestCache(manifest: Manifest): ManifestLRU {
 export function attachRouterServerSsrUtils({
   router,
   manifest,
+  getRequestAssets,
 }: {
   router: AnyRouter
   manifest: Manifest | undefined
+  getRequestAssets?: () => Array<RouterManagedTag> | undefined
 }) {
   router.ssr = {
-    manifest,
+    get manifest() {
+      const requestAssets = getRequestAssets?.()
+      if (!requestAssets?.length) return manifest
+      // Merge request-scoped assets into root route without mutating cached manifest
+      return {
+        ...manifest,
+        routes: {
+          ...manifest?.routes,
+          [rootRouteId]: {
+            ...manifest?.routes?.[rootRouteId],
+            assets: [
+              ...requestAssets,
+              ...(manifest?.routes?.[rootRouteId]?.assets ?? []),
+            ],
+          },
+        },
+      }
+    },
   }
   let _dehydrated = false
   let _serializationFinished = false
@@ -200,7 +220,7 @@ export function attachRouterServerSsrUtils({
       const html = `<script${router.options.ssr?.nonce ? ` nonce='${router.options.ssr.nonce}'` : ''}>${script}</script>`
       router.serverSsr!.injectHtml(html)
     },
-    dehydrate: async () => {
+    dehydrate: async (opts?: { requestAssets?: Array<RouterManagedTag> }) => {
       if (_dehydrated) {
         if (process.env.NODE_ENV !== 'production') {
           throw new Error('Invariant failed: router is already dehydrated!')
@@ -208,7 +228,7 @@ export function attachRouterServerSsrUtils({
 
         invariant()
       }
-      let matchesToDehydrate = router.stores.activeMatchesSnapshot.state
+      let matchesToDehydrate = router.stores.matches.get()
       if (router.isShell()) {
         // In SPA mode we only want to dehydrate the root match
         matchesToDehydrate = matchesToDehydrate.slice(0, 1)
@@ -257,6 +277,15 @@ export function attachRouterServerSsrUtils({
         manifestToDehydrate = {
           routes: filteredRoutes,
         }
+
+        // Merge request-scoped assets into root route (without mutating cached manifest)
+        if (opts?.requestAssets?.length) {
+          const existingRoot = manifestToDehydrate.routes[rootRouteId]
+          manifestToDehydrate.routes[rootRouteId] = {
+            ...existingRoot,
+            assets: [...opts.requestAssets, ...(existingRoot?.assets ?? [])],
+          }
+        }
       }
       const dehydratedRouter: DehydratedRouter = {
         manifest: manifestToDehydrate,
@@ -305,6 +334,13 @@ export function attachRouterServerSsrUtils({
           }
           scriptBuffer.enqueue(serialized)
         },
+        onError: (err: unknown) => {
+          console.error('Serialization error:', err)
+          if (err && (err as any).stack) {
+            console.error((err as any).stack)
+          }
+          signalSerializationComplete()
+        },
         scopeId: SCOPE_ID,
         onDone: () => {
           scriptBuffer.enqueue(GLOBAL_TSR + '.e()')
@@ -313,10 +349,6 @@ export function attachRouterServerSsrUtils({
           scriptBuffer.flush()
           signalSerializationComplete()
         },
-        onError: (err) => {
-          console.error('Serialization error:', err)
-          signalSerializationComplete()
-        },
       })
     },
     isDehydrated() {

package/src/ssr/transformStreamWithRouter.ts

@@ -366,6 +366,9 @@ export function transformStreamWithRouter(
       if (isAppRendering || leftover || pendingClosingTags) {
         appendRouterHtml(html)
       } else {
+        // App is done rendering - flush any pending buffer first to maintain order,
+        // then write the new HTML directly
+        flushPendingRouterHtml()
         safeEnqueue(html)
       }
     })