@tanstack/router-plugin 1.167.21 → 1.167.23

package/src/core/code-splitter/plugins/react-refresh-ignored-route-exports.ts

@@ -1,12 +1,11 @@
 import * as template from '@babel/template'
 import * as t from '@babel/types'
-import { createHmrHotExpressionAst } from '../../hmr-hot-expression'
 import { getUniqueProgramIdentifier } from '../../utils'
 import type { ReferenceRouteCompilerPlugin } from '../plugins'
 
 const buildReactRefreshIgnoredRouteExportsStatements = template.statements(
   `
-const hot = %%hotExpression%%
+const hot = import.meta.hot
 if (hot && typeof window !== 'undefined') {
   ;(hot.data ??= {})
   const tsrReactRefresh = window.__TSR_REACT_REFRESH__ ??= (() => {
@@ -41,9 +40,7 @@ const buildRefreshAnchorStatement = template.statement(
   { syntacticPlaceholders: true },
 )
 
-export function createReactRefreshIgnoredRouteExportsPlugin(opts?: {
-  hotExpression?: string
-}): ReferenceRouteCompilerPlugin {
+export function createReactRefreshIgnoredRouteExportsPlugin(): ReferenceRouteCompilerPlugin {
   return {
     name: 'react-refresh-ignored-route-exports',
     onAddHmr(ctx) {
@@ -55,9 +52,6 @@ export function createReactRefreshIgnoredRouteExportsPlugin(opts?: {
       ctx.programPath.pushContainer(
         'body',
         buildReactRefreshIgnoredRouteExportsStatements({
-          hotExpression: createHmrHotExpressionAst(
-            opts?.hotExpression ?? ctx.opts.hmrHotExpression,
-          ),
           moduleId: t.stringLiteral(ctx.opts.id),
         }),
       )

package/src/core/code-splitter/plugins/react-stable-hmr-split-route-components.ts

@@ -1,7 +1,7 @@
 import * as template from '@babel/template'
 import * as t from '@babel/types'
-import { createHmrHotExpressionAst } from '../../hmr-hot-expression'
 import { getUniqueProgramIdentifier } from '../../utils'
+import type { HmrStyle } from '../../config'
 import type { ReferenceRouteCompilerPlugin } from '../plugins'
 
 function capitalizeIdentifier(str: string) {
@@ -28,8 +28,14 @@ const buildStableSplitComponentStatements = template.statements(
   },
 )
 
-export function createReactStableHmrSplitRouteComponentsPlugin(opts?: {
-  hotExpression?: string
+function hotExpressionAstFor(hmrStyle: HmrStyle): t.Expression {
+  return template.expression.ast(
+    hmrStyle === 'webpack' ? 'import.meta.webpackHot' : 'import.meta.hot',
+  )
+}
+
+export function createReactStableHmrSplitRouteComponentsPlugin(opts: {
+  hmrStyle: HmrStyle
 }): ReferenceRouteCompilerPlugin {
   return {
     name: 'react-stable-hmr-split-route-components',
@@ -49,9 +55,7 @@ export function createReactStableHmrSplitRouteComponentsPlugin(opts?: {
         buildStableSplitComponentStatements({
           stableComponentIdent,
           hotDataKey: t.stringLiteral(hotDataKey),
-          hotExpression: createHmrHotExpressionAst(
-            opts?.hotExpression ?? ctx.opts.hmrHotExpression,
-          ),
+          hotExpression: hotExpressionAstFor(opts.hmrStyle),
           lazyRouteComponentIdent: t.identifier(ctx.lazyRouteComponentIdent),
           localImporterIdent: t.identifier(
             ctx.splitNodeMeta.localImporterIdent,

package/src/core/code-splitter/plugins.ts

@@ -1,6 +1,6 @@
 import type babel from '@babel/core'
 import type * as t from '@babel/types'
-import type { Config, DeletableNodes } from '../config'
+import type { Config, DeletableNodes, HmrStyle } from '../config'
 import type { CodeSplitGroupings } from '../constants'
 import type { SplitNodeMeta } from './types'
 
@@ -11,7 +11,8 @@ export type CompileCodeSplitReferenceRouteOptions = {
   filename: string
   id: string
   addHmr?: boolean
-  hmrHotExpression?: string
+  hmrStyle?: HmrStyle
+  hmrRouteId?: string
   sharedBindings?: Set<string>
 }
 

package/src/core/config.ts

@@ -72,8 +72,17 @@ export type CodeSplittingOptions = {
   addHmr?: boolean
 }
 
+export type HmrStyle = 'vite' | 'webpack'
+
 export type HmrOptions = {
-  hotExpression?: string
+  /**
+   * Selects the HMR runtime style to emit code for.
+   * - `'vite'` (default): ESM `import.meta.hot` with Vite accept-callback semantics.
+   * - `'webpack'`: `import.meta.webpackHot` with webpack / Rspack `module.hot` re-execution semantics.
+   *
+   * Bundler-specific plugin entries (e.g. `rspack.ts`, `webpack.ts`) set this explicitly.
+   */
+  style?: HmrStyle
 }
 
 const codeSplittingOptionsSchema = z.object({
@@ -99,7 +108,7 @@ export const configSchema = generatorConfigSchema.extend({
     .object({
       hmr: z
         .object({
-          hotExpression: z.string().optional(),
+          style: z.enum(['vite', 'webpack']).optional(),
         })
         .optional(),
       vite: z

package/src/core/{route-hmr-statement.ts → hmr/handle-route-update.ts}

@@ -1,6 +1,3 @@
-import * as template from '@babel/template'
-import { createHmrHotExpressionAst } from './hmr-hot-expression'
-import type * as t from '@babel/types'
 import type {
   AnyRoute,
   AnyRouteMatch,
@@ -25,18 +22,23 @@ type AnyRouterWithPrivateMaps = AnyRouter & {
   stores: AnyRouter['stores'] & {
     cachedMatchStores: Map<
       string,
-      Pick<RouterWritableStore<AnyRouteMatch>, 'set'>
+      Pick<RouterWritableStore<AnyRouteMatch>, 'get' | 'set'>
     >
     pendingMatchStores: Map<
       string,
-      Pick<RouterWritableStore<AnyRouteMatch>, 'set'>
+      Pick<RouterWritableStore<AnyRouteMatch>, 'get' | 'set'>
+    >
+    matchStores: Map<
+      string,
+      Pick<RouterWritableStore<AnyRouteMatch>, 'get' | 'set'>
     >
-    matchStores: Map<string, Pick<RouterWritableStore<AnyRouteMatch>, 'set'>>
   }
 }
 
 type AnyRouteMatchWithPrivateProps = AnyRouteMatch & {
   __beforeLoadContext?: unknown
+  __routeContext?: Record<string, unknown>
+  context?: Record<string, unknown>
 }
 
 function handleRouteUpdate(
@@ -69,14 +71,21 @@ function handleRouteUpdate(
     }
   })
 
+  const oldHasShellComponent = 'shellComponent' in oldRoute.options
+  const newHasShellComponent = 'shellComponent' in newRoute.options
+  const preserveComponentIdentity =
+    oldHasShellComponent === newHasShellComponent
+
   // Preserve component identity so React doesn't remount.
   // React Fast Refresh patches the function bodies in-place.
   const componentKeys = '__TSR_COMPONENT_TYPES__' as unknown as Array<string>
-  componentKeys.forEach((key) => {
-    if (key in oldRoute.options && key in newRoute.options) {
-      newRoute.options[key] = oldRoute.options[key]
-    }
-  })
+  if (preserveComponentIdentity) {
+    componentKeys.forEach((key) => {
+      if (key in oldRoute.options && key in newRoute.options) {
+        newRoute.options[key] = oldRoute.options[key]
+      }
+    })
+  }
 
   oldRoute.options = newRoute.options
   oldRoute.update(newRoute.options)
@@ -127,6 +136,7 @@ function handleRouteUpdate(
               }
               if (removedKeys.has('beforeLoad')) {
                 next.__beforeLoadContext = undefined
+                next.context = rebuildMatchContextWithoutBeforeLoad(next)
               }
 
               return next
@@ -153,37 +163,73 @@ function handleRouteUpdate(
     node.optional?.forEach((child) => walkReplaceSegmentTree(route, child))
     node.wildcard?.forEach((child) => walkReplaceSegmentTree(route, child))
   }
-}
 
-const handleRouteUpdateStr = handleRouteUpdate.toString()
+  function getStoreMatch(matchId: string) {
+    return (
+      router.stores.pendingMatchStores.get(matchId)?.get() ||
+      router.stores.matchStores.get(matchId)?.get() ||
+      router.stores.cachedMatchStores.get(matchId)?.get()
+    )
+  }
+
+  function getMatchList(matchId: string) {
+    const pendingMatches = router.stores.pendingMatches.get()
+    if (pendingMatches.some((match) => match.id === matchId)) {
+      return pendingMatches
+    }
+
+    const activeMatches = router.stores.matches.get()
+    if (activeMatches.some((match) => match.id === matchId)) {
+      return activeMatches
+    }
 
-export function createRouteHmrStatement(
-  stableRouteOptionKeys: Array<string>,
-  opts?: { hotExpression?: string },
-): t.Statement {
-  return template.statement(
-    `
-if (%%hotExpression%%) {
-  const hot = %%hotExpression%%
-  const hotData = hot.data ??= {}
-  hot.accept((newModule) => {
-    if (Route && newModule && newModule.Route) {
-      const routeId = hotData['tsr-route-id'] ?? Route.id
-      if (routeId) {
-        hotData['tsr-route-id'] = routeId
+    const cachedMatches = router.stores.cachedMatches.get()
+    if (cachedMatches.some((match) => match.id === matchId)) {
+      return cachedMatches
+    }
+
+    return []
+  }
+
+  function getParentMatch(match: AnyRouteMatch) {
+    const matchList = getMatchList(match.id)
+    const matchIndex = matchList.findIndex((item) => item.id === match.id)
+
+    if (matchIndex <= 0) {
+      return undefined
+    }
+
+    const parentMatch = matchList[matchIndex - 1]!
+    return getStoreMatch(parentMatch.id) || parentMatch
+  }
+
+  function rebuildMatchContextWithoutBeforeLoad(
+    match: AnyRouteMatchWithPrivateProps,
+  ) {
+    const parentMatch = getParentMatch(match)
+    const getParentContext = (
+      router as unknown as {
+        getParentContext?: (
+          parentMatch?: AnyRouteMatch,
+        ) => Record<string, unknown> | undefined
       }
-      (${handleRouteUpdateStr.replace(
-        /['"]__TSR_COMPONENT_TYPES__['"]/,
-        JSON.stringify(stableRouteOptionKeys),
-      )})(routeId, newModule.Route)
+    ).getParentContext
+    const parentContext = getParentContext
+      ? getParentContext.call(router, parentMatch)
+      : (parentMatch?.context ?? router.options.context)
+
+    return {
+      ...(parentContext ?? {}),
+      ...(match.__routeContext ?? {}),
     }
-    })
+  }
 }
-`,
-    {
-      syntacticPlaceholders: true,
-    },
-  )({
-    hotExpression: createHmrHotExpressionAst(opts?.hotExpression),
-  })
+
+const handleRouteUpdateStr = handleRouteUpdate.toString()
+
+export function getHandleRouteUpdateCode(stableRouteOptionKeys: Array<string>) {
+  return handleRouteUpdateStr.replace(
+    /['"]__TSR_COMPONENT_TYPES__['"]/,
+    JSON.stringify(stableRouteOptionKeys),
+  )
 }

package/src/core/hmr/index.ts

@@ -0,0 +1,5 @@
+export { createRouteHmrStatement } from './select-adapter'
+export type { CreateRouteHmrStatementOpts } from './select-adapter'
+export { createViteHmrStatement } from './vite-adapter'
+export { createWebpackHmrStatement } from './webpack-adapter'
+export { getHandleRouteUpdateCode } from './handle-route-update'

package/src/core/hmr/select-adapter.ts

@@ -0,0 +1,32 @@
+import { createViteHmrStatement } from './vite-adapter'
+import { createWebpackHmrStatement } from './webpack-adapter'
+import type { Config, HmrStyle } from '../config'
+import type * as t from '@babel/types'
+
+export type CreateRouteHmrStatementOpts = {
+  hmrStyle: HmrStyle
+  targetFramework: Config['target']
+  routeId?: string
+}
+
+/**
+ * Dispatches to the configured HMR adapter. `hmrStyle` is set explicitly by
+ * the bundler-specific plugin entry (e.g. `rspack.ts` → `'webpack'`), so there
+ * is no runtime inference based on config string shapes.
+ */
+export function createRouteHmrStatement(
+  stableRouteOptionKeys: Array<string>,
+  opts: CreateRouteHmrStatementOpts,
+): Array<t.Statement> {
+  const routeId = opts.routeId === '/__root' ? '__root__' : opts.routeId
+
+  if (opts.hmrStyle === 'webpack') {
+    return createWebpackHmrStatement(stableRouteOptionKeys, {
+      targetFramework: opts.targetFramework,
+      routeId,
+    })
+  }
+  return createViteHmrStatement(stableRouteOptionKeys, {
+    routeId,
+  })
+}

package/src/core/hmr/vite-adapter.ts

@@ -0,0 +1,47 @@
+import * as template from '@babel/template'
+import { getHandleRouteUpdateCode } from './handle-route-update'
+import type * as t from '@babel/types'
+
+/**
+ * Emits HMR accept code for Vite / native ESM HMR: `import.meta.hot.accept`
+ * with a callback that receives the freshly re-imported module.
+ *
+ * `targetFramework` is currently unused — Vite's framework-specific fast-refresh
+ * plugins handle component body patching via their own accept boundaries — but
+ * we take it for API symmetry with `createWebpackHmrStatement`.
+ */
+export function createViteHmrStatement(
+  stableRouteOptionKeys: Array<string>,
+  opts: {
+    routeId?: string
+  } = {},
+): Array<t.Statement> {
+  const handleRouteUpdateCode = getHandleRouteUpdateCode(stableRouteOptionKeys)
+  // The replacement Route object can be uninitialized; keep a generated id as
+  // fallback for the existing router route we need to patch.
+  const routeIdFallback =
+    typeof opts.routeId === 'string' ? JSON.stringify(opts.routeId) : 'Route.id'
+
+  return [
+    template.statement(
+      `
+if (import.meta.hot) {
+  const hot = import.meta.hot
+  const hotData = hot.data ??= {}
+  hot.accept((newModule) => {
+    if (Route && newModule && newModule.Route) {
+      const routeId = hotData['tsr-route-id'] ?? ${routeIdFallback}
+      if (routeId) {
+        hotData['tsr-route-id'] = routeId
+      }
+      (${handleRouteUpdateCode})(routeId, newModule.Route)
+    }
+    })
+}
+`,
+      {
+        syntacticPlaceholders: true,
+      },
+    )(),
+  ]
+}

package/src/core/hmr/webpack-adapter.ts

@@ -0,0 +1,110 @@
+import * as template from '@babel/template'
+import { getHandleRouteUpdateCode } from './handle-route-update'
+import type { Config } from '../config'
+import type * as t from '@babel/types'
+
+/**
+ * Emits HMR accept code for bundlers with webpack-compatible `module.hot`
+ * semantics (classic webpack via `import.meta.webpackHot`, and Rspack).
+ *
+ * Unlike Vite's `hot.accept((newModule) => {...})` — where the callback receives
+ * the freshly re-imported module — webpack re-executes the module factory on
+ * accept, so our HMR logic must live at module top level and read the previous
+ * `routeId` out of `hot.data`. `hot.dispose` stashes it for the next run, and
+ * `hot.accept()` (no callback) enrolls us as a self-accepting boundary.
+ *
+ * Returns an array of statements so that for React we can prepend an
+ * `import { performReactRefresh } from 'react-refresh/runtime'` hoisted to the
+ * top of the module.
+ */
+export function createWebpackHmrStatement(
+  stableRouteOptionKeys: Array<string>,
+  opts: {
+    targetFramework: Config['target']
+    routeId?: string
+  },
+): Array<t.Statement> {
+  const handleRouteUpdateCode = getHandleRouteUpdateCode(stableRouteOptionKeys)
+  const staticRouteIdLiteral =
+    typeof opts.routeId === 'string'
+      ? JSON.stringify(opts.routeId)
+      : 'undefined'
+
+  const statements: Array<t.Statement> = []
+
+  // React-only: route modules aren't React Refresh "boundaries" (they export
+  // a non-component `Route`), so the bundler's react-refresh runtime won't
+  // call `performReactRefresh` for us. We kick it manually after swapping
+  // route options so newly-registered component bodies get patched into live
+  // fibers.
+  //
+  // We import `performReactRefresh` directly from `react-refresh/runtime` —
+  // the canonical public API — rather than relying on the ProvidePlugin-
+  // injected `__react_refresh_utils__` global, whose name is an internal
+  // detail of `@rspack/plugin-react-refresh`. The rspack plugin aliases
+  // `react-refresh` → its bundled runtime (getRefreshRuntimeDirPath), so this
+  // resolves to the same singleton the plugin itself uses and shares the
+  // registry React was patched against.
+  //
+  // Use the same delayed refresh style as Rspack's React Refresh runtime.
+  // Route modules and their split component chunks can arrive in separate HMR
+  // steps under CI load; a microtask can run before the split chunk registers
+  // its new component family, causing the refresh to no-op or remount.
+  //
+  // For non-React frameworks we skip this entirely.
+  const reactRefreshCall =
+    opts.targetFramework === 'react'
+      ? `
+    const tsrRefreshState = globalThis.__TSR_HMR__ ??= {}
+    try {
+      if (!tsrRefreshState.refreshScheduled) {
+        tsrRefreshState.refreshScheduled = true
+        setTimeout(() => {
+          tsrRefreshState.refreshScheduled = false
+          try { __tsr_performReactRefresh() } catch (_e) { /* noop */ }
+        }, 30)
+      }
+    } catch (_err) { /* noop */ }`
+      : ''
+
+  if (opts.targetFramework === 'react') {
+    statements.push(
+      template.statement(
+        `import { performReactRefresh as __tsr_performReactRefresh } from 'react-refresh/runtime'`,
+      )(),
+    )
+  }
+
+  statements.push(
+    template.statement(
+      `
+if (import.meta.webpackHot) {
+  const hot = import.meta.webpackHot
+  const hotData = hot.data ??= {}
+  const routeId = hotData['tsr-route-id'] ?? Route.id ?? (Route.isRoot ? '__root__' : ${staticRouteIdLiteral})
+  if (routeId) {
+    hotData['tsr-route-id'] = routeId
+  }
+  const existingRoute =
+    typeof window !== 'undefined' && routeId
+      ? window.__TSR_ROUTER__?.routesById?.[routeId]
+      : undefined
+  if (routeId && existingRoute && existingRoute !== Route) {
+    (${handleRouteUpdateCode})(routeId, Route)${reactRefreshCall}
+  }
+  hot.dispose((data) => {
+    if (routeId) {
+      data['tsr-route-id'] = routeId
+    }
+  })
+  hot.accept()
+}
+`,
+      {
+        syntacticPlaceholders: true,
+      },
+    )(),
+  )
+
+  return statements
+}

package/src/core/router-code-splitter-plugin.ts

@@ -6,7 +6,6 @@
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { logDiff } from '@tanstack/router-utils'
 import { getConfig, splitGroupingsSchema } from './config'
-import { resolveHmrHotExpression } from './hmr-hot-expression'
 import {
   compileCodeSplitReferenceRoute,
   compileCodeSplitSharedRoute,
@@ -129,7 +128,7 @@ export const unpluginRouterCodeSplitterFactory: UnpluginFactory<
     const userShouldSplitFn = getShouldSplitFn()
 
     const pluginSplitBehavior = userShouldSplitFn?.({
-      routeId: generatorNodeInfo.routePath,
+      routeId: generatorNodeInfo.routeId,
     }) as CodeSplitGroupings | undefined
 
     if (pluginSplitBehavior) {
@@ -158,9 +157,7 @@ export const unpluginRouterCodeSplitterFactory: UnpluginFactory<
 
     const addHmr =
       (userConfig.codeSplittingOptions?.addHmr ?? true) && !isProduction
-    const hmrHotExpression = resolveHmrHotExpression(
-      userConfig.plugin?.hmr?.hotExpression,
-    )
+    const hmrStyle = userConfig.plugin?.hmr?.style ?? 'vite'
 
     const compiledReferenceRoute = compileCodeSplitReferenceRoute({
       code,
@@ -172,12 +169,13 @@ export const unpluginRouterCodeSplitterFactory: UnpluginFactory<
         ? new Set(userConfig.codeSplittingOptions.deleteNodes)
         : undefined,
       addHmr,
-      hmrHotExpression,
+      hmrStyle,
+      hmrRouteId: generatorNodeInfo.routeId,
       sharedBindings: sharedBindings.size > 0 ? sharedBindings : undefined,
       compilerPlugins: getReferenceRouteCompilerPlugins({
         targetFramework: userConfig.target,
         addHmr,
-        hmrHotExpression,
+        hmrStyle,
       }),
     })
 

package/src/core/router-composed-plugin.ts

@@ -6,12 +6,17 @@ import type { Config } from './config'
 import type { UnpluginFactory } from 'unplugin'
 
 export const unpluginRouterComposedFactory: UnpluginFactory<
-  Partial<Config> | undefined
+  Partial<Config | (() => Config)> | undefined
 > = (options = {}, meta) => {
   const ROOT: string = process.cwd()
-  const userConfig = getConfig(options, ROOT)
+  const userConfig = getConfig(
+    (typeof options === 'function' ? options() : options) as Partial<Config>,
+    ROOT,
+  )
 
-  const getPlugin = (pluginFactory: UnpluginFactory<Partial<Config>>) => {
+  const getPlugin = (
+    pluginFactory: UnpluginFactory<Partial<Config | (() => Config)>>,
+  ) => {
     const plugin = pluginFactory(options, meta)
     if (!Array.isArray(plugin)) {
       return [plugin]

package/src/core/router-hmr-plugin.ts

@@ -1,10 +1,9 @@
 import { generateFromAst, logDiff, parseAst } from '@tanstack/router-utils'
 import { compileCodeSplitReferenceRoute } from './code-splitter/compilers'
 import { getReferenceRouteCompilerPlugins } from './code-splitter/plugins/framework-plugins'
-import { createRouteHmrStatement } from './route-hmr-statement'
+import { createRouteHmrStatement } from './hmr'
 import { debug, normalizePath } from './utils'
 import { getConfig } from './config'
-import { resolveHmrHotExpression } from './hmr-hot-expression'
 import type { UnpluginFactory } from 'unplugin'
 import type { Config } from './config'
 
@@ -38,28 +37,28 @@ export const unpluginRouterHmrFactory: UnpluginFactory<
       },
       handler(code, id) {
         const normalizedId = normalizePath(id)
-        if (!globalThis.TSR_ROUTES_BY_ID_MAP?.has(normalizedId)) {
+        const routeEntry = globalThis.TSR_ROUTES_BY_ID_MAP?.get(normalizedId)
+        if (!routeEntry) {
           return null
         }
 
         if (debug) console.info('Adding HMR handling to route ', normalizedId)
 
-        const hmrHotExpression = resolveHmrHotExpression(
-          userConfig.plugin?.hmr?.hotExpression,
-        )
+        const hmrStyle = userConfig.plugin?.hmr?.style ?? 'vite'
 
         if (userConfig.target === 'react') {
           const compilerPlugins = getReferenceRouteCompilerPlugins({
             targetFramework: 'react',
             addHmr: true,
-            hmrHotExpression,
+            hmrStyle,
           })
           const compiled = compileCodeSplitReferenceRoute({
             code,
             filename: normalizedId,
             id: normalizedId,
             addHmr: true,
-            hmrHotExpression,
+            hmrStyle,
+            hmrRouteId: routeEntry.routeId,
             codeSplitGroupings: [],
             targetFramework: 'react',
             compilerPlugins,
@@ -77,7 +76,11 @@ export const unpluginRouterHmrFactory: UnpluginFactory<
 
         const ast = parseAst({ code })
         ast.program.body.push(
-          createRouteHmrStatement([], { hotExpression: hmrHotExpression }),
+          ...createRouteHmrStatement([], {
+            hmrStyle,
+            targetFramework: userConfig.target,
+            routeId: routeEntry.routeId,
+          }),
         )
         const result = generateFromAst(ast, {
           sourceMaps: true,