@tanstack/router-plugin 1.167.1 → 1.167.3

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

@@ -8,7 +8,8 @@ import {
   parseAst,
 } from '@tanstack/router-utils'
 import { tsrShared, tsrSplit } from '../constants'
-import { routeHmrStatement } from '../route-hmr-statement'
+import { createRouteHmrStatement } from '../route-hmr-statement'
+import { getObjectPropertyKeyName } from '../utils'
 import { createIdentifier } from './path-ids'
 import { getFrameworkOptions } from './framework-options'
 import type {
@@ -18,14 +19,8 @@ import type {
 import type { GeneratorResult, ParseAstOptions } from '@tanstack/router-utils'
 import type { CodeSplitGroupings, SplitRouteIdentNodes } from '../constants'
 import type { Config, DeletableNodes } from '../config'
+import type { SplitNodeMeta } from './types'
 
-type SplitNodeMeta = {
-  routeIdent: SplitRouteIdentNodes
-  splitStrategy: 'lazyFn' | 'lazyRouteComponent'
-  localImporterIdent: string
-  exporterIdent: string
-  localExporterIdent: string
-}
 const SPLIT_NODES_CONFIG = new Map<SplitRouteIdentNodes, SplitNodeMeta>([
   [
     'loader',
@@ -78,6 +73,7 @@ const SPLIT_NODES_CONFIG = new Map<SplitRouteIdentNodes, SplitNodeMeta>([
     },
   ],
 ])
+
 const KNOWN_SPLIT_ROUTE_IDENTS = [...SPLIT_NODES_CONFIG.keys()] as const
 
 function addSplitSearchParamToFilename(
@@ -297,10 +293,12 @@ export function computeSharedBindings(opts: {
   const splitGroupsPresent = new Set<number>()
   let hasNonSplit = false
   for (const prop of routeOptions.properties) {
-    if (!t.isObjectProperty(prop) || !t.isIdentifier(prop.key)) continue
-    if (prop.key.name === 'codeSplitGroupings') continue
+    if (!t.isObjectProperty(prop)) continue
+    const key = getObjectPropertyKeyName(prop)
+    if (!key) continue
+    if (key === 'codeSplitGroupings') continue
     if (t.isIdentifier(prop.value) && prop.value.name === 'undefined') continue
-    const groupIndex = findIndexForSplitNode(prop.key.name) // -1 if non-split
+    const groupIndex = findIndexForSplitNode(key) // -1 if non-split
     if (groupIndex === -1) {
       hasNonSplit = true
     } else {
@@ -333,8 +331,9 @@ export function computeSharedBindings(opts: {
   const refsByGroup = new Map<string, Set<number>>()
 
   for (const prop of routeOptions.properties) {
-    if (!t.isObjectProperty(prop) || !t.isIdentifier(prop.key)) continue
-    const key = prop.key.name
+    if (!t.isObjectProperty(prop)) continue
+    const key = getObjectPropertyKeyName(prop)
+    if (!key) continue
 
     if (key === 'codeSplitGroupings') continue
 
@@ -665,6 +664,13 @@ export function compileCodeSplitReferenceRoute(
   const PACKAGE = frameworkOptions.package
   const LAZY_ROUTE_COMPONENT_IDENT = frameworkOptions.idents.lazyRouteComponent
   const LAZY_FN_IDENT = frameworkOptions.idents.lazyFn
+  const stableRouteOptionKeys = [
+    ...new Set(
+      (opts.compilerPlugins ?? []).flatMap(
+        (plugin) => plugin.getStableRouteOptionKeys?.() ?? [],
+      ),
+    ),
+  ]
 
   let createRouteFn: string
 
@@ -702,16 +708,48 @@ export function compileCodeSplitReferenceRoute(
                 return programPath.scope.hasBinding(name)
               }
 
+              const addRouteHmr = (
+                insertionPath: babel.NodePath,
+                routeOptions: t.ObjectExpression,
+              ) => {
+                if (!opts.addHmr || hmrAdded) {
+                  return
+                }
+
+                opts.compilerPlugins?.forEach((plugin) => {
+                  const pluginResult = plugin.onAddHmr?.({
+                    programPath,
+                    callExpressionPath: path,
+                    insertionPath,
+                    routeOptions,
+                    createRouteFn,
+                    opts: opts as CompileCodeSplitReferenceRouteOptions,
+                  })
+
+                  if (pluginResult?.modified) {
+                    modified = true
+                  }
+                })
+
+                programPath.pushContainer(
+                  'body',
+                  createRouteHmrStatement(stableRouteOptionKeys),
+                )
+                modified = true
+                hmrAdded = true
+              }
+
               if (t.isObjectExpression(routeOptions)) {
+                const insertionPath = path.getStatementParent() ?? path
+
                 if (opts.deleteNodes && opts.deleteNodes.size > 0) {
                   routeOptions.properties = routeOptions.properties.filter(
                     (prop) => {
                       if (t.isObjectProperty(prop)) {
-                        if (t.isIdentifier(prop.key)) {
-                          if (opts.deleteNodes!.has(prop.key.name as any)) {
-                            modified = true
-                            return false
-                          }
+                        const key = getObjectPropertyKeyName(prop)
+                        if (key && opts.deleteNodes!.has(key as any)) {
+                          modified = true
+                          return false
                         }
                       }
                       return true
@@ -719,8 +757,6 @@ export function compileCodeSplitReferenceRoute(
                   )
                 }
                 if (!splittableCreateRouteFns.includes(createRouteFn)) {
-                  const insertionPath = path.getStatementParent() ?? path
-
                   opts.compilerPlugins?.forEach((plugin) => {
                     const pluginResult = plugin.onUnsplittableRoute?.({
                       programPath,
@@ -737,19 +773,15 @@ export function compileCodeSplitReferenceRoute(
                   })
 
                   // we can't split this route but we still add HMR handling if enabled
-                  if (opts.addHmr && !hmrAdded) {
-                    programPath.pushContainer('body', routeHmrStatement)
-                    modified = true
-                    hmrAdded = true
-                  }
+                  addRouteHmr(insertionPath, routeOptions)
                   // exit traversal so this route is not split
                   return programPath.stop()
                 }
                 routeOptions.properties.forEach((prop) => {
                   if (t.isObjectProperty(prop)) {
-                    if (t.isIdentifier(prop.key)) {
-                      const key = prop.key.name
+                    const key = getObjectPropertyKeyName(prop)
 
+                    if (key) {
                       // If the user has not specified a split grouping for this key
                       // then we should not split it
                       const codeSplitGroupingByKey = findIndexForSplitNode(key)
@@ -858,16 +890,42 @@ export function compileCodeSplitReferenceRoute(
                           ])
                         }
 
-                        prop.value = template.expression(
-                          `${LAZY_ROUTE_COMPONENT_IDENT}(${splitNodeMeta.localImporterIdent}, '${splitNodeMeta.exporterIdent}')`,
-                        )()
+                        const insertionPath = path.getStatementParent() ?? path
+                        let splitPropValue: t.Expression | undefined
+
+                        for (const plugin of opts.compilerPlugins ?? []) {
+                          const pluginPropValue = plugin.onSplitRouteProperty?.(
+                            {
+                              programPath,
+                              callExpressionPath: path,
+                              insertionPath,
+                              routeOptions,
+                              prop,
+                              splitNodeMeta,
+                              lazyRouteComponentIdent:
+                                LAZY_ROUTE_COMPONENT_IDENT,
+                            },
+                          )
+
+                          if (!pluginPropValue) {
+                            continue
+                          }
 
-                        // add HMR handling
-                        if (opts.addHmr && !hmrAdded) {
-                          programPath.pushContainer('body', routeHmrStatement)
                           modified = true
-                          hmrAdded = true
+                          splitPropValue = pluginPropValue
+                          break
+                        }
+
+                        if (splitPropValue) {
+                          prop.value = splitPropValue
+                        } else {
+                          prop.value = template.expression(
+                            `${LAZY_ROUTE_COMPONENT_IDENT}(${splitNodeMeta.localImporterIdent}, '${splitNodeMeta.exporterIdent}')`,
+                          )()
                         }
+
+                        // add HMR handling
+                        addRouteHmr(insertionPath, routeOptions)
                       } else {
                         // if (splitNodeMeta.splitStrategy === 'lazyFn') {
                         const value = prop.value
@@ -937,6 +995,8 @@ export function compileCodeSplitReferenceRoute(
 
                   programPath.scope.crawl()
                 })
+
+                addRouteHmr(insertionPath, routeOptions)
               }
             }
 
@@ -1128,10 +1188,7 @@ export function compileCodeSplitVirtualRoute(
                     // since we have special considerations that need
                     // to be accounted for like (not splitting exported identifiers)
                     KNOWN_SPLIT_ROUTE_IDENTS.forEach((splitType) => {
-                      if (
-                        !t.isIdentifier(prop.key) ||
-                        prop.key.name !== splitType
-                      ) {
+                      if (getObjectPropertyKeyName(prop) !== splitType) {
                         return
                       }
 
@@ -1673,33 +1730,32 @@ export function detectCodeSplitGroupingsFromRoute(opts: ParseAstOptions): {
               if (t.isObjectExpression(routeOptions)) {
                 routeOptions.properties.forEach((prop) => {
                   if (t.isObjectProperty(prop)) {
-                    if (t.isIdentifier(prop.key)) {
-                      if (prop.key.name === 'codeSplitGroupings') {
-                        const value = prop.value
+                    const key = getObjectPropertyKeyName(prop)
+                    if (key === 'codeSplitGroupings') {
+                      const value = prop.value
+
+                      if (t.isArrayExpression(value)) {
+                        codeSplitGroupings = value.elements.map((group) => {
+                          if (t.isArrayExpression(group)) {
+                            return group.elements.map((node) => {
+                              if (!t.isStringLiteral(node)) {
+                                throw new Error(
+                                  'You must provide a string literal for the codeSplitGroupings',
+                                )
+                              }
+
+                              return node.value
+                            }) as Array<SplitRouteIdentNodes>
+                          }
 
-                        if (t.isArrayExpression(value)) {
-                          codeSplitGroupings = value.elements.map((group) => {
-                            if (t.isArrayExpression(group)) {
-                              return group.elements.map((node) => {
-                                if (!t.isStringLiteral(node)) {
-                                  throw new Error(
-                                    'You must provide a string literal for the codeSplitGroupings',
-                                  )
-                                }
-
-                                return node.value
-                              }) as Array<SplitRouteIdentNodes>
-                            }
-
-                            throw new Error(
-                              'You must provide arrays with codeSplitGroupings options.',
-                            )
-                          })
-                        } else {
                           throw new Error(
-                            'You must provide an array of arrays for the codeSplitGroupings.',
+                            'You must provide arrays with codeSplitGroupings options.',
                           )
-                        }
+                        })
+                      } else {
+                        throw new Error(
+                          'You must provide an array of arrays for the codeSplitGroupings.',
+                        )
                       }
                     }
                   }

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

@@ -1,4 +1,6 @@
+import { createReactRefreshIgnoredRouteExportsPlugin } from './react-refresh-ignored-route-exports'
 import { createReactRefreshRouteComponentsPlugin } from './react-refresh-route-components'
+import { createReactStableHmrSplitRouteComponentsPlugin } from './react-stable-hmr-split-route-components'
 import type { ReferenceRouteCompilerPlugin } from '../plugins'
 import type { Config } from '../../config'
 
@@ -9,7 +11,11 @@ export function getReferenceRouteCompilerPlugins(opts: {
   switch (opts.targetFramework) {
     case 'react': {
       if (opts.addHmr) {
-        return [createReactRefreshRouteComponentsPlugin()]
+        return [
+          createReactRefreshIgnoredRouteExportsPlugin(),
+          createReactRefreshRouteComponentsPlugin(),
+          createReactStableHmrSplitRouteComponentsPlugin(),
+        ]
       }
       return undefined
     }

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/react-stable-hmr-split-route-components.ts

@@ -0,0 +1,56 @@
+import * as template from '@babel/template'
+import * as t from '@babel/types'
+import { getUniqueProgramIdentifier } from '../../utils'
+import type { ReferenceRouteCompilerPlugin } from '../plugins'
+
+function capitalizeIdentifier(str: string) {
+  return str[0]!.toUpperCase() + str.slice(1)
+}
+
+function createHotDataKey(exportName: string) {
+  return `tsr-split-component:${exportName}`
+}
+
+const buildStableSplitComponentStatements = template.statements(
+  `
+    const %%stableComponentIdent%% = import.meta.hot?.data?.[%%hotDataKey%%] ?? %%lazyRouteComponentIdent%%(%%localImporterIdent%%, %%exporterIdent%%)
+    if (import.meta.hot) {
+      import.meta.hot.data[%%hotDataKey%%] = %%stableComponentIdent%%
+    }
+  `,
+  {
+    syntacticPlaceholders: true,
+  },
+)
+
+export function createReactStableHmrSplitRouteComponentsPlugin(): ReferenceRouteCompilerPlugin {
+  return {
+    name: 'react-stable-hmr-split-route-components',
+    onSplitRouteProperty(ctx) {
+      if (ctx.splitNodeMeta.splitStrategy !== 'lazyRouteComponent') {
+        return
+      }
+
+      const stableComponentIdent = getUniqueProgramIdentifier(
+        ctx.programPath,
+        `TSRSplit${capitalizeIdentifier(ctx.splitNodeMeta.exporterIdent)}`,
+      )
+
+      const hotDataKey = createHotDataKey(ctx.splitNodeMeta.exporterIdent)
+
+      ctx.insertionPath.insertBefore(
+        buildStableSplitComponentStatements({
+          stableComponentIdent,
+          hotDataKey: t.stringLiteral(hotDataKey),
+          lazyRouteComponentIdent: t.identifier(ctx.lazyRouteComponentIdent),
+          localImporterIdent: t.identifier(
+            ctx.splitNodeMeta.localImporterIdent,
+          ),
+          exporterIdent: t.stringLiteral(ctx.splitNodeMeta.exporterIdent),
+        }),
+      )
+
+      return t.identifier(stableComponentIdent.name)
+    },
+  }
+}

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

@@ -2,6 +2,7 @@ import type babel from '@babel/core'
 import type * as t from '@babel/types'
 import type { Config, DeletableNodes } from '../config'
 import type { CodeSplitGroupings } from '../constants'
+import type { SplitNodeMeta } from './types'
 
 export type CompileCodeSplitReferenceRouteOptions = {
   codeSplitGroupings: CodeSplitGroupings
@@ -22,13 +23,30 @@ export type ReferenceRouteCompilerPluginContext = {
   opts: CompileCodeSplitReferenceRouteOptions
 }
 
+export type ReferenceRouteSplitPropertyCompilerPluginContext = {
+  programPath: babel.NodePath<t.Program>
+  callExpressionPath: babel.NodePath<t.CallExpression>
+  insertionPath: babel.NodePath
+  routeOptions: t.ObjectExpression
+  prop: t.ObjectProperty
+  splitNodeMeta: SplitNodeMeta
+  lazyRouteComponentIdent: string
+}
+
 export type ReferenceRouteCompilerPluginResult = {
   modified?: boolean
 }
 
 export type ReferenceRouteCompilerPlugin = {
   name: string
+  getStableRouteOptionKeys?: () => Array<string>
+  onAddHmr?: (
+    ctx: ReferenceRouteCompilerPluginContext,
+  ) => void | ReferenceRouteCompilerPluginResult
   onUnsplittableRoute?: (
     ctx: ReferenceRouteCompilerPluginContext,
   ) => void | ReferenceRouteCompilerPluginResult
+  onSplitRouteProperty?: (
+    ctx: ReferenceRouteSplitPropertyCompilerPluginContext,
+  ) => void | t.Expression
 }

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

@@ -0,0 +1,11 @@
+import type { SplitRouteIdentNodes } from '../constants'
+
+export type SplitStrategy = 'lazyFn' | 'lazyRouteComponent'
+
+export type SplitNodeMeta = {
+  routeIdent: SplitRouteIdentNodes
+  splitStrategy: SplitStrategy
+  localImporterIdent: string
+  exporterIdent: string
+  localExporterIdent: string
+}