fix: unify virtual module handling for Start Vite plugins (#7178)

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: CodeRabbit <noreply@coderabbit.ai>
Co-authored-by: schiller-manuel <schiller-manuel@users.noreply.github.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: nx-cloud[bot] <71083854+nx-cloud[bot]@users.noreply.github.com>

Author: 5 people

.changeset/rare-pigs-smash.md

@@ -0,0 +1,8 @@
+---
+'@tanstack/start-plugin-core': patch
+'@tanstack/react-start-rsc': patch
+---
+
+Fix Start virtual module resolution in pnpm workspaces by serving the client entry through a real Vite virtual module.
+
+Simplify Start virtual module handling by sharing a single `createVirtualModule` helper and collapsing internal `@tanstack/start-plugin-core` imports to the root export surface.

packages/react-start-rsc/src/plugin/vite.ts

@@ -1,49 +1,15 @@
 import { fileURLToPath } from 'node:url'
 import path from 'pathe'
-import { resolveViteId } from '@tanstack/start-plugin-core/utils'
+import { createVirtualModule } from '@tanstack/start-plugin-core'
 import type {
   TanStackStartVitePluginCoreOptions,
   ViteRscForwardSsrResolverStrategy,
-} from '@tanstack/start-plugin-core/vite/types'
-import type { Plugin, PluginOption, UserConfig } from 'vite'
+} from '@tanstack/start-plugin-core'
+import type { PluginOption, UserConfig } from 'vite'
 
-type VirtualModuleLoadHandler = (this: {
-  environment: { name: string }
-}) => string
 const isClientEnvironment = (env: { config: { consumer: string } }) =>
   env.config.consumer === 'client'
 
-function escapeRegExp(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-}
-
-function createVirtualModule(opts: {
-  name: string
-  moduleId: string
-  load: VirtualModuleLoadHandler
-  apply?: Plugin['apply']
-  applyToEnvironment?: Plugin['applyToEnvironment']
-}): Plugin {
-  const resolvedId = resolveViteId(opts.moduleId)
-  const idFilter = { id: new RegExp(escapeRegExp(opts.moduleId)) }
-
-  return {
-    name: opts.name,
-    apply: opts.apply,
-    applyToEnvironment: opts.applyToEnvironment,
-    resolveId: {
-      filter: idFilter,
-      handler() {
-        return resolvedId
-      },
-    },
-    load: {
-      filter: idFilter,
-      handler: opts.load,
-    },
-  }
-}
-
 // Virtual module ids used by the React Start RSC runtime.
 const RSC_HMR_VIRTUAL_ID = 'virtual:tanstack-rsc-hmr'
 const RSC_RUNTIME_VIRTUAL_ID = 'virtual:tanstack-rsc-runtime'

packages/react-start/src/plugin/vite.ts

@@ -2,14 +2,16 @@ import {
   START_ENVIRONMENT_NAMES,
   tanStackStartVite,
 } from '@tanstack/start-plugin-core'
+import type {
+  TanStackStartViteInputConfig,
+  TanStackStartVitePluginCoreOptions,
+} from '@tanstack/start-plugin-core'
 import {
   configureRsc,
   reactStartRscVitePlugin,
 } from '@tanstack/react-start-rsc/plugin/vite'
 import path from 'pathe'
 import { reactStartDefaultEntryPaths, reactStartPluginDir } from './shared'
-import type { TanStackStartVitePluginCoreOptions } from '@tanstack/start-plugin-core/vite/types'
-import type { TanStackStartViteInputConfig } from '@tanstack/start-plugin-core'
 import type { PluginOption } from 'vite'
 
 const isInsideRouterMonoRepo =

packages/solid-start/src/plugin/vite.ts

@@ -2,9 +2,11 @@ import {
   START_ENVIRONMENT_NAMES,
   tanStackStartVite,
 } from '@tanstack/start-plugin-core'
+import type {
+  TanStackStartViteInputConfig,
+  TanStackStartVitePluginCoreOptions,
+} from '@tanstack/start-plugin-core'
 import { solidStartDefaultEntryPaths } from './shared'
-import type { TanStackStartVitePluginCoreOptions } from '@tanstack/start-plugin-core/vite/types'
-import type { TanStackStartViteInputConfig } from '@tanstack/start-plugin-core'
 import type { PluginOption } from 'vite'
 
 export function tanstackStart(

packages/start-plugin-core/package.json

@@ -56,11 +56,6 @@
         "default": "./dist/esm/utils.js"
       }
     },
-    "./vite/types": {
-      "import": {
-        "types": "./dist/esm/vite/types.d.ts"
-      }
-    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,

packages/start-plugin-core/src/index.ts

@@ -1,6 +1,10 @@
 export type { TanStackStartInputConfig } from './schema'
 export type { TanStackStartCoreOptions } from './types'
-export type { TanStackStartVitePluginCoreOptions } from './vite/types'
+export type {
+  TanStackStartVitePluginCoreOptions,
+  ViteRscForwardSsrResolverStrategy,
+} from './vite/types'
 export type { TanStackStartViteInputConfig } from './vite/schema'
 export { START_ENVIRONMENT_NAMES, VITE_ENVIRONMENT_NAMES } from './constants'
+export { createVirtualModule } from './vite/createVirtualModule'
 export { tanStackStartVite } from './vite/plugin'

packages/start-plugin-core/src/vite/createVirtualModule.ts

@@ -0,0 +1,54 @@
+import { resolveViteId } from '../utils'
+import type { Plugin } from 'vite'
+
+type VirtualModuleLoadHandler = (
+  this: any,
+  id: string,
+) => string | null | undefined | Promise<string | null | undefined>
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+export function createVirtualModule(opts: {
+  name: string
+  moduleId: string
+  load: VirtualModuleLoadHandler
+  apply?: Plugin['apply']
+  applyToEnvironment?: Plugin['applyToEnvironment']
+  enforce?: Plugin['enforce']
+  sharedDuringBuild?: boolean
+}): Plugin {
+  // Encode '#' as '%23' in the resolved ID to avoid browser treating it as URL fragment.
+  // The browser requests /@id/__x00__%23tanstack-start-plugin-adapters instead of
+  // /@id/__x00__#tanstack-start-plugin-adapters (which would truncate at #).
+  const resolvedId = resolveViteId(opts.moduleId.replaceAll('#', '%23'))
+
+  return {
+    name: opts.name,
+    apply: opts.apply,
+    applyToEnvironment: opts.applyToEnvironment,
+    enforce: opts.enforce,
+    sharedDuringBuild: opts.sharedDuringBuild,
+    resolveId: {
+      filter: { id: new RegExp(escapeRegExp(opts.moduleId)) },
+      handler(id) {
+        if (id === opts.moduleId) {
+          return resolvedId
+        }
+
+        return undefined
+      },
+    },
+    load: {
+      filter: { id: new RegExp(escapeRegExp(resolvedId)) },
+      handler(id) {
+        if (id !== resolvedId) {
+          return undefined
+        }
+
+        return opts.load.call(this, id)
+      },
+    },
+  }
+}

packages/start-plugin-core/src/vite/dev-server-plugin/plugin.ts

@@ -2,7 +2,7 @@ import { isRunnableDevEnvironment } from 'vite'
 import { VIRTUAL_MODULES } from '@tanstack/start-server-core'
 import { NodeRequest, sendNodeResponse } from 'srvx/node'
 import { ENTRY_POINTS, VITE_ENVIRONMENT_NAMES } from '../../constants'
-import { resolveViteId } from '../../utils'
+import { createVirtualModule } from '../createVirtualModule'
 import { extractHtmlScripts } from './extract-html-scripts'
 import {
   CSS_MODULES_REGEX,
@@ -248,27 +248,17 @@ export function devServerPlugin({
         }
       },
     },
-    {
+    createVirtualModule({
       name: 'tanstack-start-core:dev-server:injected-head-scripts',
       sharedDuringBuild: true,
       applyToEnvironment: (env) => env.config.consumer === 'server',
-      resolveId: {
-        filter: { id: new RegExp(VIRTUAL_MODULES.injectedHeadScripts) },
-        handler(_id) {
-          return resolveViteId(VIRTUAL_MODULES.injectedHeadScripts)
-        },
-      },
-      load: {
-        filter: {
-          id: new RegExp(resolveViteId(VIRTUAL_MODULES.injectedHeadScripts)),
-        },
-        handler() {
-          const mod = `
+      moduleId: VIRTUAL_MODULES.injectedHeadScripts,
+      load() {
+        const mod = `
         export const injectedHeadScripts = ${JSON.stringify(injectedHeadScripts) || 'undefined'}`
-          return mod
-        },
+        return mod
       },
-    },
+    }),
   ]
 }
 

packages/start-plugin-core/src/vite/plugin.ts

@@ -25,6 +25,7 @@ import {
   createCaptureClientBuildPlugin,
   createDevBaseRewritePlugin,
   createPostBuildPlugin,
+  createVirtualClientEntryPlugin,
 } from './plugins'
 import { parseStartConfig } from './schema'
 import { startManifestPlugin } from './start-manifest-plugin/plugin'
@@ -237,6 +238,9 @@ export function tanStackStartVite(
     }),
     tanStackStartRouter(normalizedStartPluginOpts, getConfig, corePluginOpts),
     loadEnvPlugin(),
+    createVirtualClientEntryPlugin({
+      getClientEntry: () => configContext.resolveEntries().entryPaths.client,
+    }),
     startManifestPlugin({
       getClientBuild: () => getClientBuild(START_ENVIRONMENT_NAMES.client),
       getConfig,

packages/start-plugin-core/src/vite/plugins.ts

@@ -1,4 +1,6 @@
-import { START_ENVIRONMENT_NAMES } from '../constants'
+import { normalizePath } from 'vite'
+import { ENTRY_POINTS, START_ENVIRONMENT_NAMES } from '../constants'
+import { createVirtualModule } from './createVirtualModule'
 import { normalizeViteClientBuild } from './start-manifest-plugin/normalized-client-build'
 import type {
   GetConfigFn,
@@ -8,6 +10,19 @@ import type {
 import type { StartEnvironmentName } from '../constants'
 import type { PluginOption, ViteBuilder } from 'vite'
 
+export function createVirtualClientEntryPlugin(opts: {
+  getClientEntry: () => string
+}): PluginOption {
+  return createVirtualModule({
+    name: 'tanstack-start-core:virtual-client-entry',
+    moduleId: ENTRY_POINTS.client,
+    enforce: 'pre',
+    load() {
+      return `import ${JSON.stringify(normalizePath(opts.getClientEntry()).replaceAll('\\', '/'))}`
+    },
+  })
+}
+
 export function createPostBuildPlugin(opts: {
   getConfig: GetConfigFn
   postServerBuild: (opts: {