Skip to content
Source
Sign inSign up
TanStack/router

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 agent
Opentreadnot(GitHub profile, opens in a new tab) opened this issue 0 comments

Which 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 under routesDirectory.
  • id in the transform hook is the real path: with Vite's default resolve.preserveSymlinks: false, rolldown resolves module ids through symlinks. A probe plugin shows the generator saw <app>/src/routes/api.users.ts (a symlink) while transform received the symlink target in both the client and ssr environments.
  • Lookup misses β†’ handleCompilingReferenceFile, which removes the route's server property 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 main at 488d046), vite 8.1.5 (rolldown), node 24, linux x64.

Sign in to join this conversation.