@tanstack/router-plugin 1.167.2 → 1.167.3

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

@@ -0,0 +1,65 @@
+import * as template from '@babel/template'
+import * as t from '@babel/types'
+import { getUniqueProgramIdentifier } from '../../utils'
+import type { ReferenceRouteCompilerPlugin } from '../plugins'
+
+const buildReactRefreshIgnoredRouteExportsStatement = template.statement(
+  `
+if (import.meta.hot && typeof window !== 'undefined') {
+  const tsrReactRefresh = window.__TSR_REACT_REFRESH__ ??= (() => {
+    const ignoredExportsById = new Map()
+    const previousGetIgnoredExports = window.__getReactRefreshIgnoredExports
+
+    window.__getReactRefreshIgnoredExports = (ctx) => {
+      const ignoredExports = previousGetIgnoredExports?.(ctx) ?? []
+      const moduleIgnored = ignoredExportsById.get(ctx.id) ?? []
+      return [...ignoredExports, ...moduleIgnored]
+    }
+
+    return {
+      ignoredExportsById,
+    }
+  })()
+
+  tsrReactRefresh.ignoredExportsById.set(%%moduleId%%, ['Route'])
+}
+`,
+  { syntacticPlaceholders: true },
+)
+
+/**
+ * A trivial component-shaped export that gives `@vitejs/plugin-react` a valid
+ * Fast Refresh boundary. Without at least one non-ignored component export,
+ * the module would be invalidated (full page reload) on every update even
+ * though our custom route HMR handler already manages the update.
+ */
+const buildRefreshAnchorStatement = template.statement(
+  `export function %%anchorName%%() { return null }`,
+  { syntacticPlaceholders: true },
+)
+
+export function createReactRefreshIgnoredRouteExportsPlugin(): ReferenceRouteCompilerPlugin {
+  return {
+    name: 'react-refresh-ignored-route-exports',
+    onAddHmr(ctx) {
+      const anchorName = getUniqueProgramIdentifier(
+        ctx.programPath,
+        'TSRFastRefreshAnchor',
+      )
+
+      ctx.programPath.pushContainer(
+        'body',
+        buildReactRefreshIgnoredRouteExportsStatement({
+          moduleId: t.stringLiteral(ctx.opts.id),
+        }),
+      )
+
+      ctx.programPath.pushContainer(
+        'body',
+        buildRefreshAnchorStatement({ anchorName }),
+      )
+
+      return { modified: true }
+    },
+  }
+}

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

@@ -1,63 +1,92 @@
 import * as t from '@babel/types'
-import { getUniqueProgramIdentifier } from '../../utils'
+import {
+  getObjectPropertyKeyName,
+  getUniqueProgramIdentifier,
+} from '../../utils'
 import type { ReferenceRouteCompilerPlugin } from '../plugins'
 
 const REACT_REFRESH_ROUTE_COMPONENT_IDENTS = new Set([
   'component',
+  'shellComponent',
   'pendingComponent',
   'errorComponent',
   'notFoundComponent',
 ])
 
+function hoistInlineRouteComponents(ctx: {
+  programPath: Parameters<typeof getUniqueProgramIdentifier>[0]
+  insertionPath: { insertBefore: (nodes: Array<t.VariableDeclaration>) => void }
+  routeOptions: t.ObjectExpression
+}) {
+  const hoistedDeclarations: Array<t.VariableDeclaration> = []
+
+  ctx.routeOptions.properties.forEach((prop) => {
+    if (!t.isObjectProperty(prop)) {
+      return
+    }
+
+    const key = getObjectPropertyKeyName(prop)
+
+    if (!key || !REACT_REFRESH_ROUTE_COMPONENT_IDENTS.has(key)) {
+      return
+    }
+
+    if (
+      !t.isArrowFunctionExpression(prop.value) &&
+      !t.isFunctionExpression(prop.value)
+    ) {
+      return
+    }
+
+    const hoistedIdentifier = getUniqueProgramIdentifier(
+      ctx.programPath,
+      `TSR${key[0]!.toUpperCase()}${key.slice(1)}`,
+    )
+
+    hoistedDeclarations.push(
+      t.variableDeclaration('const', [
+        t.variableDeclarator(hoistedIdentifier, t.cloneNode(prop.value, true)),
+      ]),
+    )
+
+    prop.value = t.cloneNode(hoistedIdentifier)
+  })
+
+  if (hoistedDeclarations.length === 0) {
+    return false
+  }
+
+  ctx.insertionPath.insertBefore(hoistedDeclarations)
+  return true
+}
+
 export function createReactRefreshRouteComponentsPlugin(): ReferenceRouteCompilerPlugin {
   return {
     name: 'react-refresh-route-components',
+    getStableRouteOptionKeys() {
+      return [...REACT_REFRESH_ROUTE_COMPONENT_IDENTS]
+    },
     onUnsplittableRoute(ctx) {
       if (!ctx.opts.addHmr) {
         return
       }
 
-      const hoistedDeclarations: Array<t.VariableDeclaration> = []
-
-      ctx.routeOptions.properties.forEach((prop) => {
-        if (!t.isObjectProperty(prop) || !t.isIdentifier(prop.key)) {
-          return
-        }
-
-        if (!REACT_REFRESH_ROUTE_COMPONENT_IDENTS.has(prop.key.name)) {
-          return
-        }
-
-        if (
-          !t.isArrowFunctionExpression(prop.value) &&
-          !t.isFunctionExpression(prop.value)
-        ) {
-          return
-        }
-
-        const hoistedIdentifier = getUniqueProgramIdentifier(
-          ctx.programPath,
-          `TSR${prop.key.name[0]!.toUpperCase()}${prop.key.name.slice(1)}`,
-        )
-
-        hoistedDeclarations.push(
-          t.variableDeclaration('const', [
-            t.variableDeclarator(
-              hoistedIdentifier,
-              t.cloneNode(prop.value, true),
-            ),
-          ]),
-        )
-
-        prop.value = t.cloneNode(hoistedIdentifier)
-      })
-
-      if (hoistedDeclarations.length === 0) {
+      if (hoistInlineRouteComponents(ctx)) {
+        return { modified: true }
+      }
+
+      return
+    },
+    onAddHmr(ctx) {
+      if (!ctx.opts.addHmr) {
         return
       }
 
-      ctx.insertionPath.insertBefore(hoistedDeclarations)
-      return { modified: true }
+      if (hoistInlineRouteComponents(ctx)) {
+        return { modified: true }
+      }
+
+      return
     },
   }
 }

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

@@ -39,6 +39,10 @@ export type ReferenceRouteCompilerPluginResult = {
 
 export type ReferenceRouteCompilerPlugin = {
   name: string
+  getStableRouteOptionKeys?: () => Array<string>
+  onAddHmr?: (
+    ctx: ReferenceRouteCompilerPluginContext,
+  ) => void | ReferenceRouteCompilerPluginResult
   onUnsplittableRoute?: (
     ctx: ReferenceRouteCompilerPluginContext,
   ) => void | ReferenceRouteCompilerPluginResult

package/src/core/route-hmr-statement.ts

@@ -2,39 +2,145 @@ import * as template from '@babel/template'
 import type { AnyRoute, AnyRouteMatch, AnyRouter } from '@tanstack/router-core'
 
 type AnyRouteWithPrivateProps = AnyRoute & {
+  options: Record<string, unknown>
+  _componentsPromise?: Promise<void>
+  _lazyPromise?: Promise<void>
+  update: (options: Record<string, unknown>) => unknown
   _path: string
   _id: string
   _fullPath: string
   _to: string
 }
 
+type AnyRouterWithPrivateMaps = AnyRouter & {
+  routesById: Record<string, AnyRoute>
+  routesByPath: Record<string, AnyRoute>
+  stores: AnyRouter['stores'] & {
+    cachedMatchStoresById: Map<
+      string,
+      {
+        setState: (updater: (prev: AnyRouteMatch) => AnyRouteMatch) => void
+      }
+    >
+    pendingMatchStoresById: Map<
+      string,
+      {
+        setState: (updater: (prev: AnyRouteMatch) => AnyRouteMatch) => void
+      }
+    >
+    activeMatchStoresById: Map<
+      string,
+      {
+        setState: (updater: (prev: AnyRouteMatch) => AnyRouteMatch) => void
+      }
+    >
+  }
+}
+
+type AnyRouteMatchWithPrivateProps = AnyRouteMatch & {
+  __beforeLoadContext?: unknown
+}
+
 function handleRouteUpdate(
-  oldRoute: AnyRouteWithPrivateProps,
+  routeId: string,
   newRoute: AnyRouteWithPrivateProps,
 ) {
-  newRoute._path = oldRoute._path
-  newRoute._id = oldRoute._id
-  newRoute._fullPath = oldRoute._fullPath
-  newRoute._to = oldRoute._to
-  newRoute.children = oldRoute.children
-  newRoute.parentRoute = oldRoute.parentRoute
-
-  const router = window.__TSR_ROUTER__!
-  router.routesById[newRoute.id] = newRoute
-  router.routesByPath[newRoute.fullPath] = newRoute
+  const router = window.__TSR_ROUTER__ as AnyRouterWithPrivateMaps
+  const oldRoute = router.routesById[routeId] as
+    | AnyRouteWithPrivateProps
+    | undefined
+
+  if (!oldRoute) {
+    return
+  }
+
+  // Keys whose identity must remain stable to prevent React from
+  // unmounting/remounting the component tree.  React Fast Refresh already
+  // handles hot-updating the function bodies of these components — our job
+  // is only to update non-component route options (loader, head, etc.).
+  // For code-split (splittable) routes, the lazyRouteComponent wrapper is
+  // already cached in import.meta.hot.data so its identity is stable.
+  // For unsplittable routes (e.g. root routes), the component is a plain
+  // function reference that gets recreated on every module re-execution,
+  // so we must explicitly preserve the old reference.
+  const removedKeys = new Set<string>()
+  Object.keys(oldRoute.options).forEach((key) => {
+    if (!(key in newRoute.options)) {
+      removedKeys.add(key)
+      delete oldRoute.options[key]
+    }
+  })
+
+  // 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]
+    }
+  })
+
+  oldRoute.options = newRoute.options
+  oldRoute.update(newRoute.options)
+  oldRoute._componentsPromise = undefined
+  oldRoute._lazyPromise = undefined
+
+  router.routesById[oldRoute.id] = oldRoute
+  router.routesByPath[oldRoute.fullPath] = oldRoute
+
   router.processedTree.matchCache.clear()
   router.processedTree.flatCache?.clear()
   router.processedTree.singleCache.clear()
   router.resolvePathCache.clear()
-  // TODO: how to rebuild the tree if we add a new route?
-  walkReplaceSegmentTree(newRoute, router.processedTree.segmentTree)
+  walkReplaceSegmentTree(oldRoute, router.processedTree.segmentTree)
+
   const filter = (m: AnyRouteMatch) => m.routeId === oldRoute.id
-  if (
-    router.stores.activeMatchesSnapshot.state.find(filter) ||
-    router.stores.pendingMatchesSnapshot.state.find(filter)
-  ) {
-    router.invalidate({ filter })
+  const activeMatch = router.stores.activeMatchesSnapshot.state.find(filter)
+  const pendingMatch = router.stores.pendingMatchesSnapshot.state.find(filter)
+  const cachedMatches = router.stores.cachedMatchesSnapshot.state.filter(filter)
+
+  if (activeMatch || pendingMatch || cachedMatches.length > 0) {
+    // Clear stale match data for removed route options BEFORE invalidating.
+    // Without this, router.invalidate() -> matchRoutes() reuses the existing
+    // match from the store (via ...existingMatch spread) and the stale
+    // loaderData / __beforeLoadContext survives the reload cycle.
+    //
+    // We must update the store directly (not via router.updateMatch) because
+    // updateMatch wraps in startTransition which may defer the state update,
+    // and we need the clear to be visible before invalidate reads the store.
+    if (removedKeys.has('loader') || removedKeys.has('beforeLoad')) {
+      const matchIds = [
+        activeMatch?.id,
+        pendingMatch?.id,
+        ...cachedMatches.map((match) => match.id),
+      ].filter(Boolean) as Array<string>
+      router.batch(() => {
+        for (const matchId of matchIds) {
+          const store =
+            router.stores.pendingMatchStoresById.get(matchId) ||
+            router.stores.activeMatchStoresById.get(matchId) ||
+            router.stores.cachedMatchStoresById.get(matchId)
+          if (store) {
+            store.setState((prev) => {
+              const next: AnyRouteMatchWithPrivateProps = { ...prev }
+
+              if (removedKeys.has('loader')) {
+                next.loaderData = undefined
+              }
+              if (removedKeys.has('beforeLoad')) {
+                next.__beforeLoadContext = undefined
+              }
+
+              return next
+            })
+          }
+        }
+      })
+    }
+
+    router.invalidate({ filter, sync: true })
   }
+
   function walkReplaceSegmentTree(
     route: AnyRouteWithPrivateProps,
     node: AnyRouter['processedTree']['segmentTree'],
@@ -51,16 +157,26 @@ function handleRouteUpdate(
   }
 }
 
-export const routeHmrStatement = template.statement(
-  `
+const handleRouteUpdateStr = handleRouteUpdate.toString()
+
+export function createRouteHmrStatement(stableRouteOptionKeys: Array<string>) {
+  return template.statement(
+    `
 if (import.meta.hot) {
   import.meta.hot.accept((newModule) => {
     if (Route && newModule && newModule.Route) {
-      (${handleRouteUpdate.toString()})(Route, newModule.Route)
+      const routeId = import.meta.hot.data['tsr-route-id'] ?? Route.id
+      if (routeId) {
+        import.meta.hot.data['tsr-route-id'] = routeId
+      }
+      (${handleRouteUpdateStr.replace(
+        /['"]__TSR_COMPONENT_TYPES__['"]/,
+        JSON.stringify(stableRouteOptionKeys),
+      )})(routeId, newModule.Route)
     }
-   })
+    })
 }
 `,
-  // Disable placeholder parsing so identifiers like __TSR_ROUTER__ are treated as normal identifiers instead of template placeholders
-  { placeholderPattern: false },
-)()
+    { placeholderPattern: false },
+  )()
+}

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

@@ -116,7 +116,7 @@ export const unpluginRouterCodeSplitterFactory: UnpluginFactory<
       code,
     })
 
-    if (fromCode.groupings) {
+    if (fromCode.groupings !== undefined) {
       const res = splitGroupingsSchema.safeParse(fromCode.groupings)
       if (!res.success) {
         const message = res.error.errors.map((e) => e.message).join('. ')
@@ -143,7 +143,7 @@ export const unpluginRouterCodeSplitterFactory: UnpluginFactory<
     }
 
     const splitGroupings: CodeSplitGroupings =
-      fromCode.groupings || pluginSplitBehavior || getGlobalCodeSplitGroupings()
+      fromCode.groupings ?? pluginSplitBehavior ?? getGlobalCodeSplitGroupings()
 
     // Compute shared bindings before compiling the reference route
     const sharedBindings = computeSharedBindings({

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

@@ -1,7 +1,7 @@
 import { generateFromAst, logDiff, parseAst } from '@tanstack/router-utils'
 import { compileCodeSplitReferenceRoute } from './code-splitter/compilers'
 import { getReferenceRouteCompilerPlugins } from './code-splitter/plugins/framework-plugins'
-import { routeHmrStatement } from './route-hmr-statement'
+import { createRouteHmrStatement } from './route-hmr-statement'
 import { debug, normalizePath } from './utils'
 import { getConfig } from './config'
 import type { UnpluginFactory } from 'unplugin'
@@ -44,6 +44,10 @@ export const unpluginRouterHmrFactory: UnpluginFactory<
         if (debug) console.info('Adding HMR handling to route ', normalizedId)
 
         if (userConfig.target === 'react') {
+          const compilerPlugins = getReferenceRouteCompilerPlugins({
+            targetFramework: 'react',
+            addHmr: true,
+          })
           const compiled = compileCodeSplitReferenceRoute({
             code,
             filename: normalizedId,
@@ -51,10 +55,7 @@ export const unpluginRouterHmrFactory: UnpluginFactory<
             addHmr: true,
             codeSplitGroupings: [],
             targetFramework: 'react',
-            compilerPlugins: getReferenceRouteCompilerPlugins({
-              targetFramework: 'react',
-              addHmr: true,
-            }),
+            compilerPlugins,
           })
 
           if (compiled) {
@@ -68,7 +69,7 @@ export const unpluginRouterHmrFactory: UnpluginFactory<
         }
 
         const ast = parseAst({ code })
-        ast.program.body.push(routeHmrStatement)
+        ast.program.body.push(createRouteHmrStatement([]))
         const result = generateFromAst(ast, {
           sourceMaps: true,
           filename: normalizedId,

package/src/core/utils.ts

@@ -16,6 +16,24 @@ export function normalizePath(path: string): string {
   return path.replace(/\\/g, '/')
 }
 
+export function getObjectPropertyKeyName(
+  prop: t.ObjectProperty,
+): string | undefined {
+  if (prop.computed) {
+    return undefined
+  }
+
+  if (t.isIdentifier(prop.key)) {
+    return prop.key.name
+  }
+
+  if (t.isStringLiteral(prop.key)) {
+    return prop.key.value
+  }
+
+  return undefined
+}
+
 export function getUniqueProgramIdentifier(
   programPath: babel.NodePath<t.Program>,
   baseName: string,