fix: hoist inline component definitions for proper React HMR (#6919)

* fix: hoist inline component definitions for proper React HMR

this reverts #6197 and implements a proper fix

fixes #6339

* add changeset

Author: schiller-manuel

.changeset/soft-pianos-lie.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/router-plugin': patch
+'@tanstack/react-router': patch
+---
+
+fix: hoist inline component definitions for proper React HMR#6919

packages/react-router/src/Match.tsx

@@ -204,7 +204,6 @@ export const MatchInner = React.memo(function MatchInnerImpl({
           id: match.id,
           status: match.status,
           error: match.error,
-          invalid: match.invalid,
           _forcePending: match._forcePending,
           _displayPending: match._displayPending,
         },

packages/react-router/tests/router.test.tsx

@@ -1525,206 +1525,6 @@ describe('invalidate', () => {
     ).toBeInTheDocument()
     expect(screen.queryByTestId('loader-route')).not.toBeInTheDocument()
   })
-
-  /**
-   * Regression test for HMR with inline arrow function components:
-   * - When a route uses an inline arrow function for `component` (common in file-based routing),
-   *   React Refresh cannot register the component for HMR updates.
-   * - The router's HMR handler calls `router.invalidate()` to trigger updates.
-   * - The Match component must include `invalid` in its useRouterState selector so that
-   *   React detects the state change and re-renders the component.
-   * - Without this, HMR updates are sent but the UI doesn't update because React
-   *   doesn't see any state change to trigger a re-render.
-   *
-   * This test simulates HMR by:
-   * 1. Rendering a route with component v1
-   * 2. Swapping to component v2 (simulating what HMR does to route.options.component)
-   * 3. Calling router.invalidate()
-   * 4. Verifying that the NEW component v2 is now rendered
-   */
-  it('picks up new component after invalidate simulating HMR (HMR regression)', async () => {
-    const history = createMemoryHistory({
-      initialEntries: ['/hmr-test'],
-    })
-
-    const rootRoute = createRootRoute({
-      component: () => <Outlet />,
-    })
-
-    const hmrRoute = createRoute({
-      getParentRoute: () => rootRoute,
-      path: '/hmr-test',
-      // Using inline arrow function - this is what React Refresh cannot track
-      component: () => {
-        return <div data-testid="hmr-component">Version 1</div>
-      },
-    })
-
-    const router = createRouter({
-      routeTree: rootRoute.addChildren([hmrRoute]),
-      history,
-    })
-
-    render(<RouterProvider router={router} />)
-
-    await act(() => router.load())
-
-    // Verify initial component renders
-    expect(await screen.findByTestId('hmr-component')).toHaveTextContent(
-      'Version 1',
-    )
-
-    // Simulate HMR: swap the component (this is what happens when Vite hot-reloads a module)
-    hmrRoute.options.component = () => {
-      return <div data-testid="hmr-component">Version 2</div>
-    }
-
-    // Simulate HMR invalidation - this is what the router's HMR handler does
-    await act(() => router.invalidate())
-
-    // The NEW component should now be rendered
-    // Without the fix (invalid not in selector), this would still show "Version 1"
-    expect(await screen.findByTestId('hmr-component')).toHaveTextContent(
-      'Version 2',
-    )
-  })
-
-  /**
-   * Test to verify render count after invalidate (no loader).
-   * The fix should cause minimal re-renders - ideally just enough to pick up the new component.
-   */
-  it('renders minimal times after invalidate without loader (render count verification)', async () => {
-    const history = createMemoryHistory({
-      initialEntries: ['/render-count-test'],
-    })
-
-    // Use a mock to track renders across component swaps
-    const renderTracker = vi.fn()
-
-    const rootRoute = createRootRoute({
-      component: () => <Outlet />,
-    })
-
-    const testRoute = createRoute({
-      getParentRoute: () => rootRoute,
-      path: '/render-count-test',
-      component: () => {
-        renderTracker('v1')
-        return <div data-testid="test-component">Version 1</div>
-      },
-    })
-
-    const router = createRouter({
-      routeTree: rootRoute.addChildren([testRoute]),
-      history,
-    })
-
-    render(<RouterProvider router={router} />)
-    await act(() => router.load())
-
-    expect(await screen.findByTestId('test-component')).toHaveTextContent(
-      'Version 1',
-    )
-    const initialCallCount = renderTracker.mock.calls.length
-
-    // Simulate HMR: swap component (keep using same tracker)
-    testRoute.options.component = () => {
-      renderTracker('v2')
-      return <div data-testid="test-component">Version 2</div>
-    }
-
-    await act(() => router.invalidate())
-
-    expect(await screen.findByTestId('test-component')).toHaveTextContent(
-      'Version 2',
-    )
-
-    // Count renders after invalidate
-    const totalCalls = renderTracker.mock.calls.length
-    const rendersAfterInvalidate = totalCalls - initialCallCount
-
-    // We expect exactly 1 render to pick up new component
-    expect(rendersAfterInvalidate).toBe(1)
-  })
-
-  /**
-   * Test to verify render count after invalidate WITH async loader.
-   * Component consumes loader data and loader returns different data on each call.
-   */
-  it('renders minimal times after invalidate with async loader (render count verification)', async () => {
-    const history = createMemoryHistory({
-      initialEntries: ['/render-count-loader-test'],
-    })
-
-    const renderTracker = vi.fn()
-    let loaderCallCount = 0
-    const loader = vi.fn(async () => {
-      await new Promise((r) => setTimeout(r, 10))
-      loaderCallCount++
-      return { data: `loaded-${loaderCallCount}` }
-    })
-
-    const rootRoute = createRootRoute({
-      component: () => <Outlet />,
-    })
-
-    const testRoute = createRoute({
-      getParentRoute: () => rootRoute,
-      path: '/render-count-loader-test',
-      loader,
-      component: () => {
-        const loaderData = testRoute.useLoaderData()
-        renderTracker('v1', loaderData)
-        return (
-          <div data-testid="test-component">Version 1 - {loaderData.data}</div>
-        )
-      },
-    })
-
-    const router = createRouter({
-      routeTree: rootRoute.addChildren([testRoute]),
-      history,
-    })
-
-    render(<RouterProvider router={router} />)
-    await act(() => router.load())
-
-    expect(await screen.findByTestId('test-component')).toHaveTextContent(
-      'Version 1 - loaded-1',
-    )
-    const initialCallCount = renderTracker.mock.calls.length
-    const initialLoaderCalls = loader.mock.calls.length
-
-    // Simulate HMR: swap component to new version that also consumes loader data
-    testRoute.options.component = () => {
-      const loaderData = testRoute.useLoaderData()
-      renderTracker('v2', loaderData)
-      return (
-        <div data-testid="test-component">Version 2 - {loaderData.data}</div>
-      )
-    }
-
-    await act(() => router.invalidate())
-
-    // Wait for new component with new loader data
-    await waitFor(() => {
-      expect(screen.getByTestId('test-component')).toHaveTextContent(
-        'Version 2 - loaded-2',
-      )
-    })
-
-    const rendersAfterInvalidate =
-      renderTracker.mock.calls.length - initialCallCount
-    const loaderCallsAfterInvalidate =
-      loader.mock.calls.length - initialLoaderCalls
-
-    // Loader should be called once
-    expect(loaderCallsAfterInvalidate).toBe(1)
-    // Component renders twice when consuming loader data that changes:
-    // 1. Once for invalidation (new component picks up)
-    // 2. Once when new loader data arrives
-    expect(rendersAfterInvalidate).toBe(2)
-  })
 })
 
 describe('search params in URL', () => {

packages/router-plugin/src/core/code-splitter/compilers.ts

@@ -11,6 +11,10 @@ import { tsrShared, tsrSplit } from '../constants'
 import { routeHmrStatement } from '../route-hmr-statement'
 import { createIdentifier } from './path-ids'
 import { getFrameworkOptions } from './framework-options'
+import type {
+  CompileCodeSplitReferenceRouteOptions,
+  ReferenceRouteCompilerPlugin,
+} from './plugins'
 import type { GeneratorResult, ParseAstOptions } from '@tanstack/router-utils'
 import type { CodeSplitGroupings, SplitRouteIdentNodes } from '../constants'
 import type { Config, DeletableNodes } from '../config'
@@ -642,6 +646,7 @@ export function compileCodeSplitReferenceRoute(
     id: string
     addHmr?: boolean
     sharedBindings?: Set<string>
+    compilerPlugins?: Array<ReferenceRouteCompilerPlugin>
   },
 ): GeneratorResult | null {
   const ast = parseAst(opts)
@@ -714,6 +719,23 @@ export function compileCodeSplitReferenceRoute(
                   )
                 }
                 if (!splittableCreateRouteFns.includes(createRouteFn)) {
+                  const insertionPath = path.getStatementParent() ?? path
+
+                  opts.compilerPlugins?.forEach((plugin) => {
+                    const pluginResult = plugin.onUnsplittableRoute?.({
+                      programPath,
+                      callExpressionPath: path,
+                      insertionPath,
+                      routeOptions,
+                      createRouteFn,
+                      opts: opts as CompileCodeSplitReferenceRouteOptions,
+                    })
+
+                    if (pluginResult?.modified) {
+                      modified = true
+                    }
+                  })
+
                   // we can't split this route but we still add HMR handling if enabled
                   if (opts.addHmr && !hmrAdded) {
                     programPath.pushContainer('body', routeHmrStatement)

packages/router-plugin/src/core/code-splitter/plugins.ts

@@ -0,0 +1,34 @@
+import type babel from '@babel/core'
+import type * as t from '@babel/types'
+import type { Config, DeletableNodes } from '../config'
+import type { CodeSplitGroupings } from '../constants'
+
+export type CompileCodeSplitReferenceRouteOptions = {
+  codeSplitGroupings: CodeSplitGroupings
+  deleteNodes?: Set<DeletableNodes>
+  targetFramework: Config['target']
+  filename: string
+  id: string
+  addHmr?: boolean
+  sharedBindings?: Set<string>
+}
+
+export type ReferenceRouteCompilerPluginContext = {
+  programPath: babel.NodePath<t.Program>
+  callExpressionPath: babel.NodePath<t.CallExpression>
+  insertionPath: babel.NodePath
+  routeOptions: t.ObjectExpression
+  createRouteFn: string
+  opts: CompileCodeSplitReferenceRouteOptions
+}
+
+export type ReferenceRouteCompilerPluginResult = {
+  modified?: boolean
+}
+
+export type ReferenceRouteCompilerPlugin = {
+  name: string
+  onUnsplittableRoute?: (
+    ctx: ReferenceRouteCompilerPluginContext,
+  ) => void | ReferenceRouteCompilerPluginResult
+}

packages/router-plugin/src/core/code-splitter/plugins/framework-plugins.ts

@@ -0,0 +1,19 @@
+import { createReactRefreshRouteComponentsPlugin } from './react-refresh-route-components'
+import type { ReferenceRouteCompilerPlugin } from '../plugins'
+import type { Config } from '../../config'
+
+export function getReferenceRouteCompilerPlugins(opts: {
+  targetFramework: Config['target']
+  addHmr?: boolean
+}): Array<ReferenceRouteCompilerPlugin> | undefined {
+  switch (opts.targetFramework) {
+    case 'react': {
+      if (opts.addHmr) {
+        return [createReactRefreshRouteComponentsPlugin()]
+      }
+      return undefined
+    }
+    default:
+      return undefined
+  }
+}

packages/router-plugin/src/core/code-splitter/plugins/react-refresh-route-components.ts

@@ -0,0 +1,63 @@
+import * as t from '@babel/types'
+import { getUniqueProgramIdentifier } from '../../utils'
+import type { ReferenceRouteCompilerPlugin } from '../plugins'
+
+const REACT_REFRESH_ROUTE_COMPONENT_IDENTS = new Set([
+  'component',
+  'pendingComponent',
+  'errorComponent',
+  'notFoundComponent',
+])
+
+export function createReactRefreshRouteComponentsPlugin(): ReferenceRouteCompilerPlugin {
+  return {
+    name: 'react-refresh-route-components',
+    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) {
+        return
+      }
+
+      ctx.insertionPath.insertBefore(hoistedDeclarations)
+      return { modified: true }
+    },
+  }
+}