Start: symlinked route files skip the client-side `server.handlers` strip β server code and node-only imports ship in the client bundle #8514
Send to my agentWhich project does this relate to?#
Start (@tanstack/router-generator / @tanstack/router-plugin / @tanstack/start-plugin-core)
Describe the bug#
When route files are symlinks β any symlinked checkout: Bazel sandboxes, pnpm-linked source trees, Nix β vite build for a TanStack Start app ships API-route server.handlers bodies, including their node-only imports, into the client bundle. Nothing warns; the build succeeds and the app crashes in the browser on load (or, with browser-safe imports, simply exposes server code).
Mechanism. tanstack-router:code-splitter:compile-reference-file (router-code-splitter-plugin.ts) gates its transform on a map lookup:
const normalizedId = normalizePath(id)
const generatorFileInfo = routerPluginContext.routesByFile.get(normalizedId)
if (generatorFileInfo) return handleCompilingReferenceFile(code, normalizedId, generatorFileInfo)
return null // β silently skips the strip
routesByFile(Generator.getRoutesByFileMap()) is keyed by the paths the route generator scanned: the literal symlink paths underroutesDirectory.idin the transform hook is the real path: with Vite's defaultresolve.preserveSymlinks: false, rolldown resolves module ids through symlinks. A probe plugin shows the generator saw<app>/src/routes/api.users.ts(a symlink) whiletransformreceived the symlink target in both theclientandssrenvironments.- Lookup misses β
handleCompilingReferenceFile, which removes the route'sserverproperty for the client environment, never runs β the handlers and their server-only imports flow into the client graph. The HMR plugin does the same lookup and skips too.
resolve.preserveSymlinks: true makes a minimal repro pass (ids stay on the link path), but is not a general workaround: under pnpm/rules_js layouts it breaks store-internal resolution of transitive deps.
Complete minimal reproducer#
Reproduced on main (488d046) with this repo's own e2e/react-start/basic, whose src/routes/api.users.ts handler logs Fetching users... @:
# regular files: clean
cd e2e/react-start/basic && pnpm exec vite build
grep -rl 'Fetching users... @' dist/client # (nothing)
# same app, every file a symlink to the original
mkdir /tmp/basic-symlinked && cp -rs "$PWD/." /tmp/basic-symlinked/
cd /tmp/basic-symlinked && pnpm exec vite build
grep -rl 'Fetching users... @' dist/client # dist/client/assets/index-<hash>.js β the server handler, in the client bundle
Expected behavior#
The client bundle is identical whether the route files are regular files or symlinks. At minimum, a createFileRoute file inside routesDirectory that misses the map should warn loudly rather than silently produce a broken (and leaky) production bundle.
Fix#
Key routesByFile under both the scanned path and its fs.realpathSync form when they differ. PR to follow.
Environment#
- @tanstack/react-start 1.168.58, @tanstack/router-plugin 1.170.x, @tanstack/start-plugin-core 1.171.47 (repo
mainat 488d046), vite 8.1.5 (rolldown), node 24, linux x64.
treadnot(GitHub profile, opens in a new tab) linked this to #8515
Sheraff(GitHub profile, opens in a new tab) linked this to #8817
Sign in to join this conversation.