@tanstack/router-core 1.171.5 → 1.171.7

package/src/manifest.ts

@@ -1,8 +1,11 @@
 export type AssetCrossOrigin = 'anonymous' | 'use-credentials'
+export type ScriptFormat = 'module' | 'iife'
+
+export const DEV_STYLES_ATTR = 'data-tanstack-router-dev-styles'
 
 export type AssetCrossOriginConfig =
   | AssetCrossOrigin
-  | Partial<Record<'modulepreload' | 'stylesheet', AssetCrossOrigin>>
+  | Partial<Record<'script' | 'stylesheet', AssetCrossOrigin>>
 
 export type ManifestAssetLink =
   | string
@@ -13,7 +16,7 @@ export type ManifestAssetLink =
 
 export function getAssetCrossOrigin(
   assetCrossOrigin: AssetCrossOriginConfig | undefined,
-  kind: 'modulepreload' | 'stylesheet',
+  kind: 'script' | 'stylesheet',
 ): AssetCrossOrigin | undefined {
   if (!assetCrossOrigin) {
     return undefined
@@ -26,6 +29,35 @@ export function getAssetCrossOrigin(
   return assetCrossOrigin[kind]
 }
 
+export function getManifestScriptFormat(
+  manifest: { scriptFormat?: ScriptFormat } | undefined,
+): ScriptFormat {
+  return manifest?.scriptFormat ?? 'module'
+}
+
+export function getScriptPreloadAttrs(
+  manifest: { scriptFormat?: ScriptFormat } | undefined,
+  link: ManifestAssetLink,
+  assetCrossOrigin?: AssetCrossOriginConfig,
+): {
+  rel: 'modulepreload' | 'preload'
+  as?: 'script'
+  href: string
+  crossOrigin?: AssetCrossOrigin
+} {
+  const preloadLink = resolveManifestAssetLink(link)
+  const crossOrigin =
+    getAssetCrossOrigin(assetCrossOrigin, 'script') ?? preloadLink.crossOrigin
+
+  return {
+    ...(getManifestScriptFormat(manifest) === 'iife'
+      ? { rel: 'preload', as: 'script' }
+      : { rel: 'modulepreload' }),
+    href: preloadLink.href,
+    ...(crossOrigin ? { crossOrigin } : {}),
+  }
+}
+
 export function resolveManifestAssetLink(link: ManifestAssetLink) {
   if (typeof link === 'string') {
     return { href: link, crossOrigin: undefined }
@@ -35,87 +67,147 @@ export function resolveManifestAssetLink(link: ManifestAssetLink) {
 }
 
 export type Manifest = {
-  inlineCss?: {
-    styles: Record<string, string>
-    templates?: Record<
-      string,
-      {
-        strings: Array<string>
-        urls: Array<string>
-      }
-    >
-  }
-  routes: Record<
-    string,
-    {
-      filePath?: string
-      preloads?: Array<ManifestAssetLink>
-      assets?: Array<RouterManagedTag>
-    }
-  >
+  scriptFormat?: ScriptFormat
+  inlineStyle?: ManifestInlineCss
+  routes: Record<string, ManifestRoute>
+}
+
+export type ServerManifest = {
+  scriptFormat?: ScriptFormat
+  inlineCss?: ServerManifestInlineCss
+  routes: Record<string, ServerManifestRoute>
+}
+
+export type ServerManifestInlineCss = {
+  styles: Record<string, string>
+  templates?: Record<string, InlineCssTemplate>
+}
+
+export type InlineCssTemplate = {
+  strings: Array<string>
+  urls: Array<string>
+}
+
+export type ManifestRoute = {
+  filePath?: string
+  preloads?: Array<ManifestAssetLink>
+  scripts?: Array<ManifestScript>
+  css?: Array<ManifestCssLink>
+}
+
+export type ServerManifestRoute = ManifestRoute
+
+export type ManifestRouteAssets = Pick<
+  ManifestRoute,
+  'preloads' | 'scripts' | 'css'
+>
+
+export type RouterManagedTitleTag = {
+  tag: 'title'
+  attrs?: Record<string, any>
+  children: string
+}
+
+export type RouterManagedMetaTag = {
+  tag: 'meta'
+  attrs?: Record<string, any>
+  children?: never
+}
+
+export type RouterManagedLinkTag = {
+  tag: 'link'
+  attrs?: Record<string, any>
+  children?: never
+}
+
+export type RouterManagedScriptTag = {
+  tag: 'script'
+  attrs?: Record<string, any>
+  children?: string
+}
+
+export type ManifestScript = Omit<RouterManagedScriptTag, 'tag'>
+
+export type RouterManagedStyleTag = {
+  tag: 'style'
+  attrs?: Record<string, any>
+  children?: string
+  inlineCss?: true
 }
 
 export type RouterManagedTag =
-  | {
-      tag: 'title'
-      attrs?: Record<string, any>
-      children: string
-    }
-  | {
-      tag: 'meta' | 'link'
-      attrs?: Record<string, any>
-      children?: never
-    }
-  | {
-      tag: 'script'
-      attrs?: Record<string, any>
-      children?: string
+  | RouterManagedTitleTag
+  | RouterManagedMetaTag
+  | RouterManagedLinkTag
+  | RouterManagedScriptTag
+  | RouterManagedStyleTag
+
+export function appendUniqueUserTags(
+  target: Array<RouterManagedTag>,
+  tags: Array<RouterManagedTag>,
+) {
+  if (tags.length === 0) {
+    return
+  }
+
+  if (tags.length === 1) {
+    target.push(tags[0]!)
+    return
+  }
+
+  const seen = new Set<string>()
+  for (const tag of tags) {
+    const key = JSON.stringify(tag)
+    if (seen.has(key)) {
+      continue
     }
+    seen.add(key)
+    target.push(tag)
+  }
+}
+
+export type ManifestCssLink =
+  | string
   | {
-      tag: 'style'
-      attrs?: Record<string, any>
-      children?: string
-      inlineCss?: true
+      href: string
+      crossOrigin?: AssetCrossOrigin
+      [DEV_STYLES_ATTR]?: true
     }
 
-export function getStylesheetHref(asset: RouterManagedTag) {
-  if (asset.tag !== 'link') return undefined
-
-  const rel = asset.attrs?.rel
-  const href = asset.attrs?.href
-  if (typeof href !== 'string') return undefined
+export type ManifestInlineCss = {
+  attrs?: Record<string, any>
+  children?: string
+}
 
-  const relTokens = typeof rel === 'string' ? rel.split(/\s+/) : []
-  if (!relTokens.includes('stylesheet')) return undefined
+export type RouterManagedInlineCssTag = RouterManagedStyleTag & {
+  inlineCss: true
+}
 
-  return href
+export function getStylesheetHref(asset: ManifestCssLink) {
+  return resolveManifestCssLink(asset).href
 }
 
-export function isInlinableStylesheet(
-  manifest: Manifest | undefined,
-  asset: RouterManagedTag,
-) {
-  const href = getStylesheetHref(asset)
-  return !!href && manifest?.inlineCss?.styles[href] !== undefined
+export function resolveManifestCssLink(link: ManifestCssLink) {
+  if (typeof link === 'string') {
+    return { href: link, crossOrigin: undefined }
+  }
+
+  return link
 }
 
-export function createInlineCssStyleAsset(css: string): RouterManagedTag {
+export function createInlineCssStyleAsset(css: string): ManifestInlineCss {
   return {
-    tag: 'style',
     attrs: {
       suppressHydrationWarning: true,
     },
-    inlineCss: true,
     children: css,
   }
 }
 
-export function createInlineCssPlaceholderAsset(): RouterManagedTag {
+export function createInlineCssPlaceholderAsset(): ManifestInlineCss {
   return {
-    tag: 'style',
     attrs: {
       suppressHydrationWarning: true,
     },
-    inlineCss: true,
   }
 }

package/src/router.ts

@@ -98,7 +98,11 @@ import type {
   CommitLocationOptions,
   NavigateFn,
 } from './RouterProvider'
-import type { Manifest, RouterManagedTag } from './manifest'
+import type {
+  Manifest,
+  ManifestRouteAssets,
+  RouterManagedTag,
+} from './manifest'
 import type { AnySchema, AnyValidator } from './validators'
 import type { NavigateOptions, ResolveRelativePath, ToOptions } from './link'
 import type { NotFoundError } from './not-found'
@@ -341,9 +345,8 @@ export interface RouterOptions<
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#dehydrate-method)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/external-data-loading#critical-dehydrationhydration)
    */
-  dehydrate?: () => Constrain<
-    TDehydrated,
-    ValidateSerializableInput<Register, TDehydrated>
+  dehydrate?: () => Awaitable<
+    Constrain<TDehydrated, ValidateSerializableInput<Register, TDehydrated>>
   >
   /**
    * A function that will be called when the router is hydrated.
@@ -787,34 +790,47 @@ export type ClearCacheFn<TRouter extends AnyRouter> = (opts?: {
 }) => void
 
 export interface ServerSsr {
-  /**
-   * Injects HTML synchronously into the stream.
-   * Emits an onInjectedHtml event that listeners can handle.
-   * If no subscriber is listening, the HTML is buffered and can be retrieved via takeBufferedHtml().
-   */
+  /** Framework-only: injects router-owned HTML into the SSR stream. */
   injectHtml: (html: string) => void
-  /**
-   * Injects a script tag synchronously into the stream.
-   */
+  /** Framework-only: injects a router-owned script tag into the SSR stream. */
   injectScript: (script: string) => void
   isDehydrated: () => boolean
   isSerializationFinished: () => boolean
+  /** Framework-only: atomically reserves the pass-through stream path if safe. */
+  reserveStreamFastPath: () => boolean
+  /** Framework-only. */
+  onInjectedHtml: (listener: () => void) => () => void
+  /** Framework-only. */
   onRenderFinished: (listener: () => void) => void
+  /** Framework-only. */
   setRenderFinished: () => void
+  /** Framework-only. */
   cleanup: () => void
-  onSerializationFinished: (listener: () => void) => void
-  dehydrate: (opts?: {
-    requestAssets?: Array<RouterManagedTag>
-  }) => Promise<void>
-  takeBufferedScripts: () => RouterManagedTag | undefined
   /**
-   * Takes any buffered HTML that was injected.
-   * Returns the buffered HTML string (which may include multiple script tags) or undefined if empty.
+   * Register a listener invoked when the SSR request lifecycle ends (success,
+   * error, abort, or stream lifetime expiry). Use to tear down per-request
+   * resources whose references would otherwise pin the router (e.g. query
+   * cache subscriptions, gcTime timers, abort controllers).
+   *
+   * Listeners run synchronously and exactly once. Errors are caught and logged.
    */
+  onCleanup: (listener: () => void) => void
+  /** Framework-only. */
+  onSerializationFinished: (listener: () => void) => () => void
+  /** Framework-only. */
+  dehydrate: (opts?: { requestAssets?: ManifestRouteAssets }) => Promise<void>
+  /** Framework-only. */
+  takeBufferedScripts: () => RouterManagedTag | undefined
+  /** Framework-only: takes buffered router-owned HTML. */
   takeBufferedHtml: () => string | undefined
+  /** Framework-only. */
   liftScriptBarrier: () => void
 }
 
+export interface RouterSsrLifecycle {
+  onServerSsrAttach?: Array<(serverSsr: ServerSsr) => void>
+}
+
 export type AnyRouterWithContext<TContext> = RouterCore<
   AnyRouteWithContext<TContext>,
   any,
@@ -2975,6 +2991,8 @@ export class RouterCore<
 
   serverSsr?: ServerSsr
 
+  serverSsrLifecycle?: RouterSsrLifecycle
+
   hasNotFoundMatch = () => {
     return this.stores.matches
       .get()

package/src/ssr/createRequestHandler.ts

@@ -5,10 +5,11 @@ import {
   getNormalizedURL,
   getOrigin,
 } from './ssr-server'
+import { normalizeSsrResponse } from './handlerCallback'
 import type { HandlerCallback } from './handlerCallback'
 import type { AnyHeaders } from './headers'
 import type { AnyRouter } from '../router'
-import type { Manifest } from '../manifest'
+import type { ServerManifest } from '../manifest'
 
 export type RequestHandler<TRouter extends AnyRouter> = (
   cb: HandlerCallback<TRouter>,
@@ -21,12 +22,11 @@ export function createRequestHandler<TRouter extends AnyRouter>({
 }: {
   createRouter: () => TRouter
   request: Request
-  getRouterManifest?: () => Manifest | Promise<Manifest>
+  getRouterManifest?: () => ServerManifest | Promise<ServerManifest>
 }): RequestHandler<TRouter> {
   return async (cb) => {
     const router = createRouter()
-    // Track whether the callback will handle cleanup
-    let cbWillCleanup = false
+    let responseOwnsCleanup = false
 
     try {
       attachRouterServerSsrUtils({
@@ -58,19 +58,19 @@ export function createRequestHandler<TRouter extends AnyRouter>({
         router,
       })
 
-      // Mark that the callback will handle cleanup
-      cbWillCleanup = true
-      return cb({
+      const response = await cb({
         request,
         router,
         responseHeaders,
       })
+      const ssrResponse = normalizeSsrResponse(response)
+      responseOwnsCleanup = ssrResponse.serverSsrCleanup === 'stream'
+      return ssrResponse.response
     } finally {
-      if (!cbWillCleanup) {
+      if (!responseOwnsCleanup) {
         // Clean up router SSR state if the callback won't handle it
         // (e.g., if an error occurred before the callback was invoked).
-        // When the callback runs, it handles cleanup (either via transformStreamWithRouter
-        // for streaming, or directly in renderRouterToString for non-streaming).
+        // Transformed streaming response bodies clean up when consumed/cancelled.
         router.serverSsr?.cleanup()
       }
     }
@@ -78,9 +78,10 @@ export function createRequestHandler<TRouter extends AnyRouter>({
 }
 
 function getRequestHeaders(opts: { router: AnyRouter }): Headers {
-  const matchHeaders = opts.router.stores.matches
-    .get()
-    .map<AnyHeaders>((match) => match.headers)
+  const matchHeaders: Array<AnyHeaders> = []
+  for (const match of opts.router.stores.matches.get()) {
+    matchHeaders.push(match.headers)
+  }
 
   // Handle Redirects
   const redirect = opts.router.stores.redirect.get()

package/src/ssr/handlerCallback.ts

@@ -1,11 +1,94 @@
 import type { AnyRouter } from '../router'
 
+export type SsrResponse =
+  | {
+      response: Response
+      serverSsrCleanup: 'none'
+    }
+  | {
+      response: Response
+      serverSsrCleanup: 'stream'
+      dispose: (reason?: unknown) => Promise<void>
+    }
+
+export type HandlerCallbackResult = Response | SsrResponse
+
+export function isSsrResponse(value: unknown): value is SsrResponse {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'response' in value &&
+    'serverSsrCleanup' in value
+  )
+}
+
+export function normalizeSsrResponse(
+  result: HandlerCallbackResult,
+): SsrResponse {
+  return isSsrResponse(result)
+    ? result
+    : { response: result, serverSsrCleanup: 'none' }
+}
+
+export function createSsrStreamResponse<TRouter extends AnyRouter>(
+  router: TRouter,
+  response: Response,
+): SsrResponse {
+  if (!response.body) {
+    throw new Error('Invariant failed: SSR stream response requires a body')
+  }
+
+  let disposed = false
+  return {
+    response,
+    serverSsrCleanup: 'stream',
+    async dispose(reason?: unknown) {
+      if (disposed) return
+      disposed = true
+
+      try {
+        await response.body!.cancel(reason)
+      } catch {
+        // ignore; fallback cleanup below still releases router SSR state
+      }
+
+      router.serverSsr?.cleanup()
+    },
+  }
+}
+
+export async function replaceSsrResponse(
+  result: HandlerCallbackResult,
+  response: Response,
+  reason?: unknown,
+): Promise<SsrResponse> {
+  const ssrResponse = normalizeSsrResponse(result)
+  if (ssrResponse.serverSsrCleanup === 'stream') {
+    await ssrResponse.dispose(reason)
+  }
+  return { response, serverSsrCleanup: 'none' }
+}
+
+export async function stripSsrResponseBody(
+  result: HandlerCallbackResult,
+  reason?: unknown,
+): Promise<SsrResponse> {
+  const ssrResponse = normalizeSsrResponse(result)
+  if (ssrResponse.serverSsrCleanup === 'stream') {
+    await ssrResponse.dispose(reason)
+  }
+  return {
+    response: new Response(null, ssrResponse.response),
+    serverSsrCleanup: 'none',
+  }
+}
+
 export interface HandlerCallback<TRouter extends AnyRouter> {
   (ctx: {
     request: Request
     router: TRouter
     responseHeaders: Headers
-  }): Response | Promise<Response>
+  }): HandlerCallbackResult | Promise<HandlerCallbackResult>
 }
 
 export function defineHandlerCallback<TRouter extends AnyRouter>(

package/src/ssr/server.ts

@@ -1,12 +1,24 @@
 export { createRequestHandler } from './createRequestHandler'
 export type { RequestHandler } from './createRequestHandler'
-export { defineHandlerCallback } from './handlerCallback'
-export type { HandlerCallback } from './handlerCallback'
+export {
+  createSsrStreamResponse,
+  defineHandlerCallback,
+  isSsrResponse,
+  normalizeSsrResponse,
+  replaceSsrResponse,
+  stripSsrResponseBody,
+} from './handlerCallback'
+export type {
+  HandlerCallback,
+  HandlerCallbackResult,
+  SsrResponse,
+} from './handlerCallback'
 export {
   transformPipeableStreamWithRouter,
   transformStreamWithRouter,
   transformReadableStreamWithRouter,
 } from './transformStreamWithRouter'
+export type { TransformStreamWithRouterOptions } from './transformStreamWithRouter'
 export {
   attachRouterServerSsrUtils,
   getNormalizedURL,