@tanstack/router-core 1.121.0-alpha.27 → 1.121.0-alpha.28

package/src/scroll-restoration.ts

@@ -2,6 +2,7 @@ import { functionalUpdate } from './utils'
 import type { AnyRouter } from './router'
 import type { ParsedLocation } from './location'
 import type { NonNullableUpdater } from './utils'
+import type { HistoryLocation } from '@tanstack/history'
 
 export type ScrollRestorationEntry = { scrollX: number; scrollY: number }
 
@@ -79,7 +80,7 @@ export const scrollRestorationCache = createScrollRestorationCache()
  */
 
 export const defaultGetScrollRestorationKey = (location: ParsedLocation) => {
-  return location.state.key! || location.href
+  return location.state.__TSR_key! || location.href
 }
 
 export function getCssSelector(el: any): string {
@@ -100,15 +101,21 @@ let ignoreScroll = false
 // unless they are passed in as arguments. Why? Because we need to be able to
 // toString() it into a script tag to execute as early as possible in the browser
 // during SSR. Additionally, we also call it from within the router lifecycle
-export function restoreScroll(
-  storageKey: string,
-  key: string | undefined,
-  behavior: ScrollToOptions['behavior'] | undefined,
-  shouldScrollRestoration: boolean | undefined,
-  scrollToTopSelectors:
-    | Array<string | (() => Element | null | undefined)>
-    | undefined,
-) {
+export function restoreScroll({
+  storageKey,
+  key,
+  behavior,
+  shouldScrollRestoration,
+  scrollToTopSelectors,
+  location,
+}: {
+  storageKey: string
+  key?: string
+  behavior?: ScrollToOptions['behavior']
+  shouldScrollRestoration?: boolean
+  scrollToTopSelectors?: Array<string | (() => Element | null | undefined)>
+  location?: HistoryLocation
+}) {
   let byKey: ScrollRestorationByKey
 
   try {
@@ -128,7 +135,11 @@ export function restoreScroll(
   ;(() => {
     // If we have a cached entry for this location state,
     // we always need to prefer that over the hash scroll.
-    if (shouldScrollRestoration && elementEntries) {
+    if (
+      shouldScrollRestoration &&
+      elementEntries &&
+      Object.keys(elementEntries).length > 0
+    ) {
       for (const elementSelector in elementEntries) {
         const entry = elementEntries[elementSelector]!
         if (elementSelector === 'window') {
@@ -153,7 +164,7 @@ export function restoreScroll(
     // Which means we've never seen this location before,
     // we need to check if there is a hash in the URL.
     // If there is, we need to scroll it's ID into view.
-    const hash = window.location.hash.split('#')[1]
+    const hash = (location ?? window.location).hash.split('#')[1]
 
     if (hash) {
       const hashScrollIntoViewOptions =
@@ -321,13 +332,14 @@ export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
       return
     }
 
-    restoreScroll(
+    restoreScroll({
       storageKey,
-      cacheKey,
-      router.options.scrollRestorationBehavior || undefined,
-      router.isScrollRestoring || undefined,
-      router.options.scrollToTopSelectors || undefined,
-    )
+      key: cacheKey,
+      behavior: router.options.scrollRestorationBehavior,
+      shouldScrollRestoration: router.isScrollRestoring,
+      scrollToTopSelectors: router.options.scrollToTopSelectors,
+      location: router.history.location,
+    })
 
     if (router.isScrollRestoring) {
       // Mark the location as having been seen

package/src/ssr/client.ts

@@ -0,0 +1,5 @@
+export { mergeHeaders, headersInitToObject } from './headers'
+export { json } from './json'
+export type { JsonResponse } from './json'
+export { hydrate } from './ssr-client'
+export * from './ssr-client'

package/src/ssr/createRequestHandler.ts

@@ -0,0 +1,74 @@
+import { createMemoryHistory } from '@tanstack/history'
+import { mergeHeaders } from './headers'
+import { attachRouterServerSsrUtils } from './ssr-server'
+import type { HandlerCallback } from './handlerCallback'
+import type { AnyRouter } from '../router'
+import type { Manifest } from '../manifest'
+
+export type RequestHandler<TRouter extends AnyRouter> = (
+  cb: HandlerCallback<TRouter>,
+) => Promise<Response>
+
+export function createRequestHandler<TRouter extends AnyRouter>({
+  createRouter,
+  request,
+  getRouterManifest,
+}: {
+  createRouter: () => TRouter
+  request: Request
+  getRouterManifest?: () => Manifest | Promise<Manifest>
+}): RequestHandler<TRouter> {
+  return async (cb) => {
+    const router = createRouter()
+
+    attachRouterServerSsrUtils(router, await getRouterManifest?.())
+
+    const url = new URL(request.url, 'http://localhost')
+
+    const href = url.href.replace(url.origin, '')
+
+    // Create a history for the router
+    const history = createMemoryHistory({
+      initialEntries: [href],
+    })
+
+    // Update the router with the history and context
+    router.update({
+      history,
+    })
+
+    await router.load()
+
+    await router.serverSsr?.dehydrate()
+
+    const responseHeaders = getRequestHeaders({
+      router,
+    })
+
+    return cb({
+      request,
+      router,
+      responseHeaders,
+    } as any)
+  }
+}
+
+function getRequestHeaders(opts: { router: AnyRouter }): Headers {
+  let headers = mergeHeaders(
+    {
+      'Content-Type': 'text/html; charset=UTF-8',
+    },
+    ...opts.router.state.matches.map((match) => {
+      return match.headers
+    }),
+  )
+
+  // Handle Redirects
+  const { redirect } = opts.router.state
+
+  if (redirect) {
+    headers = mergeHeaders(headers, redirect.headers)
+  }
+
+  return headers
+}

package/src/ssr/handlerCallback.ts

@@ -0,0 +1,15 @@
+import type { AnyRouter } from '../router'
+
+export interface HandlerCallback<TRouter extends AnyRouter> {
+  (ctx: {
+    request: Request
+    router: TRouter
+    responseHeaders: Headers
+  }): Response | Promise<Response>
+}
+
+export function defineHandlerCallback<TRouter extends AnyRouter>(
+  handler: HandlerCallback<TRouter>,
+): HandlerCallback<TRouter> {
+  return handler
+}

package/src/ssr/headers.ts

@@ -0,0 +1,51 @@
+import { splitSetCookieString } from 'cookie-es'
+import type { OutgoingHttpHeaders } from 'node:http2'
+
+// A utility function to turn HeadersInit into an object
+export function headersInitToObject(
+  headers: HeadersInit,
+): Record<keyof OutgoingHttpHeaders, string> {
+  const obj: Record<keyof OutgoingHttpHeaders, string> = {}
+  const headersInstance = new Headers(headers)
+  for (const [key, value] of headersInstance.entries()) {
+    obj[key] = value
+  }
+  return obj
+}
+
+type AnyHeaders =
+  | Headers
+  | HeadersInit
+  | Record<string, string>
+  | Array<[string, string]>
+  | OutgoingHttpHeaders
+  | undefined
+
+// Helper function to convert various HeaderInit types to a Headers instance
+function toHeadersInstance(init: AnyHeaders) {
+  if (init instanceof Headers) {
+    return new Headers(init)
+  } else if (Array.isArray(init)) {
+    return new Headers(init)
+  } else if (typeof init === 'object') {
+    return new Headers(init as HeadersInit)
+  } else {
+    return new Headers()
+  }
+}
+
+// Function to merge headers with proper overrides
+export function mergeHeaders(...headers: Array<AnyHeaders>) {
+  return headers.reduce((acc: Headers, header) => {
+    const headersInstance = toHeadersInstance(header)
+    for (const [key, value] of headersInstance.entries()) {
+      if (key === 'set-cookie') {
+        const splitCookies = splitSetCookieString(value)
+        splitCookies.forEach((cookie) => acc.append('set-cookie', cookie))
+      } else {
+        acc.set(key, value)
+      }
+    }
+    return acc
+  }, new Headers())
+}

package/src/ssr/json.ts

@@ -0,0 +1,18 @@
+import { mergeHeaders } from './headers'
+
+export interface JsonResponse<TData> extends Response {
+  json: () => Promise<TData>
+}
+
+export function json<TData>(
+  payload: TData,
+  init?: ResponseInit,
+): JsonResponse<TData> {
+  return new Response(JSON.stringify(payload), {
+    ...init,
+    headers: mergeHeaders(
+      { 'content-type': 'application/json' },
+      init?.headers,
+    ),
+  })
+}

package/src/ssr/seroval-plugins.ts

@@ -0,0 +1,43 @@
+import { createPlugin } from 'seroval'
+import type { SerovalNode } from 'seroval'
+
+interface ErrorNode {
+  message: SerovalNode
+}
+
+/**
+ * this plugin serializes only the `message` part of an Error
+ * this helps with serializing e.g. a ZodError which has functions attached that cannot be serialized
+ */
+export const ShallowErrorPlugin = /* @__PURE__ */ createPlugin<
+  Error,
+  ErrorNode
+>({
+  tag: 'tanstack-start:seroval-plugins/Error',
+  test(value) {
+    return value instanceof Error
+  },
+  parse: {
+    sync(value, ctx) {
+      return {
+        message: ctx.parse(value.message),
+      }
+    },
+    async async(value, ctx) {
+      return {
+        message: await ctx.parse(value.message),
+      }
+    },
+    stream(value, ctx) {
+      return {
+        message: ctx.parse(value.message),
+      }
+    },
+  },
+  serialize(node, ctx) {
+    return 'new Error(' + ctx.serialize(node.message) + ')'
+  },
+  deserialize(node, ctx) {
+    return new Error(ctx.deserialize(node.message) as string)
+  },
+})

package/src/ssr/server.ts

@@ -0,0 +1,10 @@
+export { createRequestHandler } from './createRequestHandler'
+export type { RequestHandler } from './createRequestHandler'
+export { defineHandlerCallback } from './handlerCallback'
+export type { HandlerCallback } from './handlerCallback'
+export {
+  transformPipeableStreamWithRouter,
+  transformStreamWithRouter,
+  transformReadableStreamWithRouter,
+} from './transformStreamWithRouter'
+export { attachRouterServerSsrUtils } from './ssr-server'

package/src/ssr/ssr-client.ts

@@ -0,0 +1,242 @@
+import invariant from 'tiny-invariant'
+import { batch } from '@tanstack/store'
+import { createControlledPromise } from '../utils'
+import type { AnyRouteMatch, MakeRouteMatch } from '../Matches'
+import type { AnyRouter } from '../router'
+import type { Manifest } from '../manifest'
+import type { RouteContextOptions } from '../route'
+import type { GLOBAL_TSR } from './ssr-server'
+
+declare global {
+  interface Window {
+    [GLOBAL_TSR]?: TsrSsrGlobal
+  }
+}
+
+export interface TsrSsrGlobal {
+  router?: DehydratedRouter
+  // clean scripts, shortened since this is sent for each streamed script
+  c: () => void
+}
+
+function hydrateMatch(
+  deyhydratedMatch: DehydratedMatch,
+): Partial<MakeRouteMatch> {
+  return {
+    id: deyhydratedMatch.i,
+    __beforeLoadContext: deyhydratedMatch.b,
+    loaderData: deyhydratedMatch.l,
+    status: deyhydratedMatch.s,
+    ssr: deyhydratedMatch.ssr,
+    updatedAt: deyhydratedMatch.u,
+    error: deyhydratedMatch.e,
+  }
+}
+export interface DehydratedMatch {
+  i: MakeRouteMatch['id']
+  b?: MakeRouteMatch['__beforeLoadContext']
+  l?: MakeRouteMatch['loaderData']
+  e?: MakeRouteMatch['error']
+  u: MakeRouteMatch['updatedAt']
+  s: MakeRouteMatch['status']
+  ssr?: MakeRouteMatch['ssr']
+}
+
+export interface DehydratedRouter {
+  manifest: Manifest | undefined
+  dehydratedData?: any
+  lastMatchId?: string
+  matches: Array<DehydratedMatch>
+}
+
+export async function hydrate(router: AnyRouter): Promise<any> {
+  invariant(
+    window.$_TSR?.router,
+    'Expected to find a dehydrated data on window.$_TSR.router, but we did not. Please file an issue!',
+  )
+
+  const { manifest, dehydratedData, lastMatchId } = window.$_TSR.router
+
+  router.ssr = {
+    manifest,
+  }
+
+  // Hydrate the router state
+  const matches = router.matchRoutes(router.state.location)
+
+  // kick off loading the route chunks
+  const routeChunkPromise = Promise.all(
+    matches.map((match) => {
+      const route = router.looseRoutesById[match.routeId]!
+      return router.loadRouteChunk(route)
+    }),
+  )
+
+  function setMatchForcePending(match: AnyRouteMatch) {
+    // usually the minPendingPromise is created in the Match component if a pending match is rendered
+    // however, this might be too late if the match synchronously resolves
+    const route = router.looseRoutesById[match.routeId]!
+    const pendingMinMs =
+      route.options.pendingMinMs ?? router.options.defaultPendingMinMs
+    if (pendingMinMs) {
+      const minPendingPromise = createControlledPromise<void>()
+      match.minPendingPromise = minPendingPromise
+      match._forcePending = true
+
+      setTimeout(() => {
+        minPendingPromise.resolve()
+        // We've handled the minPendingPromise, so we can delete it
+        router.updateMatch(match.id, (prev) => ({
+          ...prev,
+          minPendingPromise: undefined,
+          _forcePending: undefined,
+        }))
+      }, pendingMinMs)
+    }
+  }
+
+  // Right after hydration and before the first render, we need to rehydrate each match
+  // First step is to reyhdrate loaderData and __beforeLoadContext
+  let firstNonSsrMatchIndex: number | undefined = undefined
+  matches.forEach((match) => {
+    const dehydratedMatch = window.$_TSR!.router!.matches.find(
+      (d) => d.i === match.id,
+    )
+    if (!dehydratedMatch) {
+      Object.assign(match, { dehydrated: false, ssr: false })
+      return
+    }
+
+    Object.assign(match, hydrateMatch(dehydratedMatch))
+
+    if (match.ssr === false) {
+      match._dehydrated = false
+    } else {
+      match._dehydrated = true
+    }
+
+    if (match.ssr === 'data-only' || match.ssr === false) {
+      if (firstNonSsrMatchIndex === undefined) {
+        firstNonSsrMatchIndex = match.index
+        setMatchForcePending(match)
+      }
+    }
+  })
+
+  router.__store.setState((s) => {
+    return {
+      ...s,
+      matches,
+    }
+  })
+
+  // Allow the user to handle custom hydration data
+  await router.options.hydrate?.(dehydratedData)
+
+  // now that all necessary data is hydrated:
+  // 1) fully reconstruct the route context
+  // 2) execute `head()` and `scripts()` for each match
+  await Promise.all(
+    router.state.matches.map(async (match) => {
+      const route = router.looseRoutesById[match.routeId]!
+
+      const parentMatch = router.state.matches[match.index - 1]
+      const parentContext = parentMatch?.context ?? router.options.context ?? {}
+
+      // `context()` was already executed by `matchRoutes`, however route context was not yet fully reconstructed
+      // so run it again and merge route context
+      const contextFnContext: RouteContextOptions<any, any, any, any> = {
+        deps: match.loaderDeps,
+        params: match.params,
+        context: parentContext,
+        location: router.state.location,
+        navigate: (opts: any) =>
+          router.navigate({ ...opts, _fromLocation: router.state.location }),
+        buildLocation: router.buildLocation,
+        cause: match.cause,
+        abortController: match.abortController,
+        preload: false,
+        matches,
+      }
+      match.__routeContext = route.options.context?.(contextFnContext) ?? {}
+
+      match.context = {
+        ...parentContext,
+        ...match.__routeContext,
+        ...match.__beforeLoadContext,
+      }
+
+      const assetContext = {
+        matches: router.state.matches,
+        match,
+        params: match.params,
+        loaderData: match.loaderData,
+      }
+      const headFnContent = await route.options.head?.(assetContext)
+
+      const scripts = await route.options.scripts?.(assetContext)
+
+      match.meta = headFnContent?.meta
+      match.links = headFnContent?.links
+      match.headScripts = headFnContent?.scripts
+      match.styles = headFnContent?.styles
+      match.scripts = scripts
+    }),
+  )
+
+  const isSpaMode = matches[matches.length - 1]!.id !== lastMatchId
+  const hasSsrFalseMatches = matches.some((m) => m.ssr === false)
+  // all matches have data from the server   and we are not in SPA mode so we don't need to kick of router.load()
+  if (!hasSsrFalseMatches && !isSpaMode) {
+    matches.forEach((match) => {
+      // remove the _dehydrate flag since we won't run router.load() which would remove it
+      match._dehydrated = undefined
+    })
+    return routeChunkPromise
+  }
+
+  // schedule router.load() to run after the next tick so we can store the promise in the match before loading starts
+  const loadPromise = Promise.resolve()
+    .then(() => router.load())
+    .catch((err) => {
+      console.error('Error during router hydration:', err)
+    })
+
+  // in SPA mode we need to keep the first match below the root route pending until router.load() is finished
+  // this will prevent that other pending components are rendered but hydration is not blocked
+  if (isSpaMode) {
+    const match = matches[1]
+    invariant(
+      match,
+      'Expected to find a match below the root match in SPA mode.',
+    )
+    setMatchForcePending(match)
+
+    match._displayPending = true
+    match.displayPendingPromise = loadPromise
+
+    loadPromise.then(() => {
+      batch(() => {
+        // 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.__store.state.status === 'pending') {
+          router.__store.setState((s) => ({
+            ...s,
+            status: 'idle',
+            resolvedLocation: s.location,
+          }))
+        }
+        // hide the pending component once the load is finished
+        router.updateMatch(match.id, (prev) => {
+          return {
+            ...prev,
+            _displayPending: undefined,
+            displayPendingPromise: undefined,
+          }
+        })
+      })
+    })
+  }
+  return routeChunkPromise
+}

package/src/ssr/ssr-server.ts

@@ -0,0 +1,132 @@
+import { crossSerializeStream, getCrossReferenceHeader } from 'seroval'
+import { ReadableStreamPlugin } from 'seroval-plugins/web'
+import invariant from 'tiny-invariant'
+import { createControlledPromise } from '../utils'
+import minifiedTsrBootStrapScript from './tsrScript?script-string'
+import { ShallowErrorPlugin } from './seroval-plugins'
+import type { AnyRouter } from '../router'
+import type { DehydratedMatch } from './ssr-client'
+import type { DehydratedRouter } from './client'
+import type { AnyRouteMatch } from '../Matches'
+import type { Manifest } from '../manifest'
+
+declare module '../router' {
+  interface ServerSsr {
+    setRenderFinished: () => void
+  }
+  interface RouterEvents {
+    onInjectedHtml: {
+      type: 'onInjectedHtml'
+      promise: Promise<string>
+    }
+  }
+}
+
+export const GLOBAL_TSR = '$_TSR'
+const SCOPE_ID = 'tsr'
+
+export function dehydrateMatch(match: AnyRouteMatch): DehydratedMatch {
+  const dehydratedMatch: DehydratedMatch = {
+    i: match.id,
+    u: match.updatedAt,
+    s: match.status,
+  }
+
+  const properties = [
+    ['__beforeLoadContext', 'b'],
+    ['loaderData', 'l'],
+    ['error', 'e'],
+    ['ssr', 'ssr'],
+  ] as const
+
+  for (const [key, shorthand] of properties) {
+    if (match[key] !== undefined) {
+      dehydratedMatch[shorthand] = match[key]
+    }
+  }
+  return dehydratedMatch
+}
+
+export function attachRouterServerSsrUtils(
+  router: AnyRouter,
+  manifest: Manifest | undefined,
+) {
+  router.ssr = {
+    manifest,
+  }
+  const serializationRefs = new Map<unknown, number>()
+
+  let initialScriptSent = false
+  const getInitialScript = () => {
+    if (initialScriptSent) {
+      return ''
+    }
+    initialScriptSent = true
+    return `${getCrossReferenceHeader(SCOPE_ID)};${minifiedTsrBootStrapScript};`
+  }
+  let _dehydrated = false
+  const listeners: Array<() => void> = []
+
+  router.serverSsr = {
+    injectedHtml: [],
+    injectHtml: (getHtml) => {
+      const promise = Promise.resolve().then(getHtml)
+      router.serverSsr!.injectedHtml.push(promise)
+      router.emit({
+        type: 'onInjectedHtml',
+        promise,
+      })
+
+      return promise.then(() => {})
+    },
+    injectScript: (getScript) => {
+      return router.serverSsr!.injectHtml(async () => {
+        const script = await getScript()
+        return `<script class='$tsr'>${getInitialScript()}${script};if (typeof $_TSR !== 'undefined') $_TSR.c()</script>`
+      })
+    },
+    dehydrate: async () => {
+      invariant(!_dehydrated, 'router is already dehydrated!')
+      let matchesToDehydrate = router.state.matches
+      if (router.isShell()) {
+        // In SPA mode we only want to dehydrate the root match
+        matchesToDehydrate = matchesToDehydrate.slice(0, 1)
+      }
+      const matches = matchesToDehydrate.map(dehydrateMatch)
+
+      const dehydratedRouter: DehydratedRouter = {
+        manifest: router.ssr!.manifest,
+        matches,
+      }
+      const lastMatchId = matchesToDehydrate[matchesToDehydrate.length - 1]?.id
+      if (lastMatchId) {
+        dehydratedRouter.lastMatchId = lastMatchId
+      }
+      dehydratedRouter.dehydratedData = await router.options.dehydrate?.()
+      _dehydrated = true
+
+      const p = createControlledPromise<string>()
+      crossSerializeStream(dehydratedRouter, {
+        refs: serializationRefs,
+        // TODO make plugins configurable
+        plugins: [ReadableStreamPlugin, ShallowErrorPlugin],
+        onSerialize: (data, initial) => {
+          const serialized = initial ? `${GLOBAL_TSR}["router"]=` + data : data
+          router.serverSsr!.injectScript(() => serialized)
+        },
+        scopeId: SCOPE_ID,
+        onDone: () => p.resolve(''),
+        onError: (err) => p.reject(err),
+      })
+      // make sure the stream is kept open until the promise is resolved
+      router.serverSsr!.injectHtml(() => p)
+    },
+    isDehydrated() {
+      return _dehydrated
+    },
+    onRenderFinished: (listener) => listeners.push(listener),
+    setRenderFinished: () => {
+      listeners.forEach((l) => l())
+    },
+  }
+}