fix(router-plugin): fix critical code splitting bugs identified by reviewer

Addresses three critical runtime bugs found in PR review:

1. **Bare specifier imports** - Dynamic imports and static imports were using
   bare specifiers (e.g., "file.tsx") instead of relative paths ("./file.tsx"),
   causing bundler resolution failures.

2. **Importing non-exported variables** - Virtual split files were importing
   variables that weren't exported in the reference file, resulting in undefined
   at runtime.

3. **Missing metadata flow** - Virtual compiler had no way to know which
   variables were promoted to exports in the reference file.

**Solutions implemented:**

- Updated `addSplitSearchParamFromFilename` and `removeSplitSearchParamFromFilename`
  to ensure all import specifiers use relative paths with "./" prefix

- Added `sharedExports` metadata flow from reference compilation to virtual
  compilation via plugin-layer cache

- Virtual compiler now only imports variables confirmed to be in the shared
  exports set, preventing undefined imports

- Updated tests to simulate the plugin's caching behavior

**Edge cases tested:**

- Multiple shared variables
- Already exported variables
- Multiple declarations in same statement
- Call expression initializers
- Variable dependencies
- Objects with methods
- Nested function usage

All 288 tests passing. Users no longer need to manually export variables -
the code splitter automatically handles sharing between split and non-split
parts.

Reviewer feedback: #5767

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: KyleAMathews

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

@@ -81,16 +81,24 @@ function addSplitSearchParamToFilename(
 ) {
   const [bareFilename] = filename.split('?')
 
+  // Ensure relative import specifier for proper bundler resolution
+  const relativeFilename = bareFilename!.startsWith('./') || bareFilename!.startsWith('../')
+    ? bareFilename!
+    : `./${bareFilename!}`
+
   const params = new URLSearchParams()
   params.append(tsrSplit, createIdentifier(grouping))
 
-  const result = `${bareFilename}?${params.toString()}`
+  const result = `${relativeFilename}?${params.toString()}`
   return result
 }
 
 function removeSplitSearchParamFromFilename(filename: string) {
   const [bareFilename] = filename.split('?')
-  return bareFilename!
+  // Ensure relative import specifier for proper bundler resolution
+  return bareFilename!.startsWith('./') || bareFilename!.startsWith('../')
+    ? bareFilename!
+    : `./${bareFilename!}`
 }
 
 const splittableCreateRouteFns = ['createFileRoute']
@@ -111,6 +119,7 @@ export function compileCodeSplitReferenceRoute(
     filename: string
     id: string
     addHmr?: boolean
+    sharedExports?: Set<string>
   },
 ): GeneratorResult | null {
   const ast = parseAst(opts)
@@ -536,6 +545,8 @@ export function compileCodeSplitReferenceRoute(
                 const exportDecl = t.exportNamedDeclaration(varDecl.node, [])
                 varDecl.replaceWith(exportDecl)
                 knownExportedIdents.add(identName)
+                // Track in sharedExports for virtual compiler to use
+                opts.sharedExports?.add(identName)
               }
             }
           })
@@ -580,6 +591,7 @@ export function compileCodeSplitVirtualRoute(
   opts: ParseAstOptions & {
     splitTargets: Array<SplitRouteIdentNodes>
     filename: string
+    sharedExports?: Set<string>
   },
 ): GeneratorResult {
   const ast = parseAst(opts)
@@ -880,86 +892,52 @@ export function compileCodeSplitVirtualRoute(
           },
         })
 
-        // Convert non-exported module-level variables that are shared with the reference file
-        // to imports. These are variables used by both split and non-split parts.
-        // They will be exported in the reference file, so we need to import them here.
-        const importedSharedIdents = new Set<string>()
-        const sharedVariablesToImport: Array<string> = []
-
-        programPath.traverse({
-          VariableDeclaration(varDeclPath) {
-            // Only process top-level const/let declarations
-            if (!varDeclPath.parentPath.isProgram()) return
-            if (varDeclPath.node.kind !== 'const' && varDeclPath.node.kind !== 'let') return
-
-            varDeclPath.node.declarations.forEach((declarator) => {
-              if (!t.isIdentifier(declarator.id)) return
+        // Import shared module-level variables that were exported in the reference file
+        // Only process variables confirmed to be in the sharedExports set
+        if (opts.sharedExports && opts.sharedExports.size > 0) {
+          const variablesToImport: Array<string> = []
 
-              const varName = declarator.id.name
-
-              // Skip if the init is a function/arrow function - those are unlikely to be shared objects
-              // We only want to import object literals and similar data structures
-              if (
-                t.isArrowFunctionExpression(declarator.init) ||
-                t.isFunctionExpression(declarator.init)
-              ) {
-                return
-              }
-
-              // Check if this variable is used by the split node
-              // If it is, it might be shared with non-split parts and should be imported
-              const isUsedBySplitNode = intendedSplitNodes.values().next().value &&
-                Object.values(trackedNodesToSplitByType).some(tracked => {
-                  if (!tracked?.node) return false
-                  let isUsed = false
-                  babel.traverse(tracked.node, {
-                    Identifier(idPath) {
-                      if (idPath.isReferencedIdentifier() && idPath.node.name === varName) {
-                        isUsed = true
-                      }
-                    }
-                  }, programPath.scope)
-                  return isUsed
-                })
-
-              if (isUsedBySplitNode) {
-                sharedVariablesToImport.push(varName)
-              }
-            })
-          },
-        })
-
-        // Remove shared variable declarations and add imports
-        if (sharedVariablesToImport.length > 0) {
           programPath.traverse({
             VariableDeclaration(varDeclPath) {
+              // Only process top-level const/let declarations
               if (!varDeclPath.parentPath.isProgram()) return
+              if (varDeclPath.node.kind !== 'const' && varDeclPath.node.kind !== 'let') return
+
+              varDeclPath.node.declarations.forEach((declarator) => {
+                if (!t.isIdentifier(declarator.id)) return
 
-              const declaratorsToKeep = varDeclPath.node.declarations.filter((declarator) => {
-                if (!t.isIdentifier(declarator.id)) return true
                 const varName = declarator.id.name
 
-                if (sharedVariablesToImport.includes(varName)) {
-                  importedSharedIdents.add(varName)
-                  return false // Remove this declarator
+                // Only import if this variable is in the confirmed shared exports set
+                if (opts.sharedExports!.has(varName)) {
+                  variablesToImport.push(varName)
                 }
-                return true
               })
-
-              if (declaratorsToKeep.length === 0) {
-                // Remove the entire variable declaration
-                varDeclPath.remove()
-              } else if (declaratorsToKeep.length < varDeclPath.node.declarations.length) {
-                // Update with remaining declarators
-                varDeclPath.node.declarations = declaratorsToKeep
-              }
             },
           })
 
-          // Add import statement for shared variables
-          if (importedSharedIdents.size > 0) {
+          // Remove shared variable declarations and add imports
+          if (variablesToImport.length > 0) {
+            programPath.traverse({
+              VariableDeclaration(varDeclPath) {
+                if (!varDeclPath.parentPath.isProgram()) return
+
+                const declaratorsToKeep = varDeclPath.node.declarations.filter((declarator) => {
+                  if (!t.isIdentifier(declarator.id)) return true
+                  return !variablesToImport.includes(declarator.id.name)
+                })
+
+                if (declaratorsToKeep.length === 0) {
+                  varDeclPath.remove()
+                } else if (declaratorsToKeep.length < varDeclPath.node.declarations.length) {
+                  varDeclPath.node.declarations = declaratorsToKeep
+                }
+              },
+            })
+
+            // Add import statement for shared variables
             const importDecl = t.importDeclaration(
-              Array.from(importedSharedIdents).map((name) =>
+              variablesToImport.map((name) =>
                 t.importSpecifier(t.identifier(name), t.identifier(name)),
               ),
               t.stringLiteral(removeSplitSearchParamFromFilename(opts.filename)),

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

@@ -66,6 +66,10 @@ export const unpluginRouterCodeSplitterFactory: UnpluginFactory<
   let ROOT: string = process.cwd()
   let userConfig: Config
 
+  // Cache of shared module-level variables that were exported in reference files
+  // Key: base filename (without query params), Value: Set of exported identifier names
+  const sharedExportsCache = new Map<string, Set<string>>()
+
   function initUserConfig() {
     if (typeof options === 'function') {
       userConfig = options()
@@ -125,6 +129,7 @@ export const unpluginRouterCodeSplitterFactory: UnpluginFactory<
     const splitGroupings: CodeSplitGroupings =
       fromCode.groupings || pluginSplitBehavior || getGlobalCodeSplitGroupings()
 
+    const sharedExports = new Set<string>()
     const compiledReferenceRoute = compileCodeSplitReferenceRoute({
       code,
       codeSplitGroupings: splitGroupings,
@@ -136,8 +141,15 @@ export const unpluginRouterCodeSplitterFactory: UnpluginFactory<
         : undefined,
       addHmr:
         (userConfig.codeSplittingOptions?.addHmr ?? true) && !isProduction,
+      sharedExports,
     })
 
+    // Cache shared exports for virtual route compilation
+    if (sharedExports.size > 0) {
+      const baseFilename = id.split('?')[0]!
+      sharedExportsCache.set(baseFilename, sharedExports)
+    }
+
     if (compiledReferenceRoute === null) {
       if (debug) {
         console.info(
@@ -176,10 +188,15 @@ export const unpluginRouterCodeSplitterFactory: UnpluginFactory<
       splitRouteIdentNodes.includes(p as any),
     ) as Array<SplitRouteIdentNodes>
 
+    // Get shared exports from cache for this route
+    const baseFilename = id.split('?')[0]!
+    const sharedExports = sharedExportsCache.get(baseFilename)
+
     const result = compileCodeSplitVirtualRoute({
       code,
       filename: id,
       splitTargets: grouping,
+      sharedExports,
     })
 
     if (debug) {

packages/router-plugin/tests/code-splitter.test.ts

@@ -52,21 +52,31 @@ describe('code-splitter works', () => {
         const dirs = getFrameworkDir(framework)
         const filenames = await readdir(dirs.files)
 
+        // Cache for shared exports per filename
+        const sharedExportsCache = new Map<string, Set<string>>()
+
         it.each(filenames)(
           `should compile "reference" for "%s"`,
           async (filename) => {
             const file = await readFile(path.join(dirs.files, filename))
             const code = file.toString()
 
+            const sharedExports = new Set<string>()
             const compileResult = compileCodeSplitReferenceRoute({
               code,
               filename,
               id: filename,
               addHmr: false,
               codeSplitGroupings: grouping,
               targetFramework: framework,
+              sharedExports,
             })
 
+            // Cache shared exports for virtual compilation
+            if (sharedExports.size > 0) {
+              sharedExportsCache.set(filename, sharedExports)
+            }
+
             await expect(compileResult?.code || code).toMatchFileSnapshot(
               path.join(dirs.snapshots, groupName, filename),
             )
@@ -79,13 +89,17 @@ describe('code-splitter works', () => {
             const file = await readFile(path.join(dirs.files, filename))
             const code = file.toString()
 
+            // Get shared exports from cache
+            const sharedExports = sharedExportsCache.get(filename)
+
             for (const targets of grouping) {
               const ident = createIdentifier(targets)
 
               const splitResult = compileCodeSplitVirtualRoute({
                 code,
                 filename: `${filename}?${ident}`,
                 splitTargets: targets,
+                sharedExports,
               })
 
               const snapshotFilename = path.join(

packages/router-plugin/tests/code-splitter/snapshots/react/1-default/arrow-function.tsx

@@ -1,4 +1,4 @@
-const $$splitComponentImporter = () => import('arrow-function.tsx?tsr-split=component');
+const $$splitComponentImporter = () => import('./arrow-function.tsx?tsr-split=component');
 import { lazyRouteComponent } from '@tanstack/react-router';
 import * as React from 'react';
 import { createFileRoute } from '@tanstack/react-router';

packages/router-plugin/tests/code-splitter/snapshots/react/1-default/arrow-function@component.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { Link, Outlet } from '@tanstack/react-router';
-import { Route } from "arrow-function.tsx";
+import { Route } from "./arrow-function.tsx";
 const PostsComponent = () => {
   const posts = Route.useLoaderData();
   return <div className="p-2 flex gap-2">

packages/router-plugin/tests/code-splitter/snapshots/react/1-default/boolean-null-literals.tsx

@@ -1,4 +1,4 @@
-const $$splitComponentImporter = () => import('boolean-null-literals.tsx?tsr-split=component');
+const $$splitComponentImporter = () => import('./boolean-null-literals.tsx?tsr-split=component');
 import { lazyRouteComponent } from '@tanstack/react-router';
 import { createFileRoute } from '@tanstack/router';
 

packages/router-plugin/tests/code-splitter/snapshots/react/1-default/chinese.tsx

@@ -1,4 +1,4 @@
-const $$splitComponentImporter = () => import('chinese.tsx?tsr-split=component');
+const $$splitComponentImporter = () => import('./chinese.tsx?tsr-split=component');
 import { lazyRouteComponent } from '@tanstack/react-router';
 import * as React from 'react';
 import { createFileRoute } from '@tanstack/react-router';

packages/router-plugin/tests/code-splitter/snapshots/react/1-default/circular-reference-arrow-function.tsx

@@ -1,4 +1,4 @@
-const $$splitComponentImporter = () => import('circular-reference-arrow-function.tsx?tsr-split=component');
+const $$splitComponentImporter = () => import('./circular-reference-arrow-function.tsx?tsr-split=component');
 import { lazyRouteComponent } from '@tanstack/react-router';
 import { createFileRoute } from '@tanstack/react-router';
 export const Route = createFileRoute('/')({

packages/router-plugin/tests/code-splitter/snapshots/react/1-default/circular-reference-function.tsx

@@ -1,4 +1,4 @@
-const $$splitComponentImporter = () => import('circular-reference-function.tsx?tsr-split=component');
+const $$splitComponentImporter = () => import('./circular-reference-function.tsx?tsr-split=component');
 import { lazyRouteComponent } from '@tanstack/react-router';
 import { createFileRoute } from '@tanstack/react-router';
 export const Route = createFileRoute('/')({

packages/router-plugin/tests/code-splitter/snapshots/react/1-default/conditional-properties.tsx

@@ -1,4 +1,4 @@
-const $$splitComponentImporter = () => import('conditional-properties.tsx?tsr-split=component');
+const $$splitComponentImporter = () => import('./conditional-properties.tsx?tsr-split=component');
 import { lazyRouteComponent } from '@tanstack/react-router';
 import { createFileRoute } from '@tanstack/react-router';
 import { isEnabled } from '@features/feature-flags';