@tanstack/router-plugin 1.167.1 → 1.167.3

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,
@@ -23,13 +41,20 @@ export function getUniqueProgramIdentifier(
   let name = baseName
   let suffix = 2
 
+  const programScope = programPath.scope.getProgramParent()
+
   while (
-    programPath.scope.hasBinding(name) ||
-    programPath.scope.hasGlobal(name)
+    programScope.hasBinding(name) ||
+    programScope.hasGlobal(name) ||
+    programScope.hasReference(name)
   ) {
     name = `${baseName}${suffix}`
     suffix++
   }
 
+  // Register the name so subsequent calls within the same traversal
+  // see it and avoid collisions
+  programScope.references[name] = true
+
   return t.identifier(name)
 }