@tanstack/start-plugin-core 1.167.18 → 1.167.19

package/src/{start-compiler-plugin → start-compiler}/compiler.ts

@@ -15,6 +15,7 @@ import { handleEnvOnlyFn } from './handleEnvOnly'
 import { handleClientOnlyJSX } from './handleClientOnlyJSX'
 import type {
   CompilationContext,
+  DevServerFnModuleSpecifierEncoder,
   MethodChainPaths,
   RewriteCandidate,
   ServerFn,
@@ -311,9 +312,6 @@ export class StartCompiler {
   private entryIdToFunctionId = new Map<string, string>()
   private functionIds = new Set<string>()
 
-  // Cached root path with trailing slash for dev mode function ID generation
-  private _rootWithTrailingSlash: string | undefined
-
   constructor(
     private options: {
       env: 'client' | 'server'
@@ -353,6 +351,7 @@ export class StartCompiler {
        * Used by server callers to look up canonical extracted filenames.
        */
       getKnownServerFns?: () => Record<string, ServerFn>
+      devServerFnModuleSpecifierEncoder?: DevServerFnModuleSpecifierEncoder
     },
   ) {
     this.validLookupKinds = options.lookupKinds
@@ -369,12 +368,20 @@ export class StartCompiler {
     extractedFilename: string
   }): string {
     if (this.mode === 'dev') {
-      // In dev, encode the file path and export name for direct lookup
-      let file = opts.extractedFilename
-      if (opts.extractedFilename.startsWith(this.rootWithTrailingSlash)) {
-        file = opts.extractedFilename.slice(this.rootWithTrailingSlash.length)
+      // In dev, encode the file path and export name for direct lookup.
+      // Each bundler adapter supplies its own strategy for encoding
+      // module specifiers that work with its dev server runtime.
+      const encodeModuleSpecifier =
+        this.options.devServerFnModuleSpecifierEncoder
+      if (!encodeModuleSpecifier) {
+        throw new Error(
+          'devServerFnModuleSpecifierEncoder is required in dev mode.',
+        )
       }
-      file = `/@id/${file}`
+      const file = encodeModuleSpecifier({
+        extractedFilename: opts.extractedFilename,
+        root: this.options.root,
+      })
 
       const serverFn = {
         file,
@@ -415,15 +422,6 @@ export class StartCompiler {
     return this.options.mode ?? 'dev'
   }
 
-  private get rootWithTrailingSlash(): string {
-    if (this._rootWithTrailingSlash === undefined) {
-      this._rootWithTrailingSlash = this.options.root.endsWith('/')
-        ? this.options.root
-        : `${this.options.root}/`
-    }
-    return this._rootWithTrailingSlash
-  }
-
   private async resolveIdCached(id: string, importer?: string) {
     if (this.mode === 'dev') {
       return this.options.resolveId(id, importer)
@@ -460,54 +458,62 @@ export class StartCompiler {
       ]),
     )
 
-    await Promise.all(
-      this.options.lookupConfigurations.map(async (config) => {
-        // Populate the fast lookup map for direct imports (by package name)
-        // This allows O(1) recognition of imports from known packages.
-        let libExports = this.knownRootImports.get(config.libName)
-        if (!libExports) {
-          libExports = new Map()
-          this.knownRootImports.set(config.libName, libExports)
-        }
-        libExports.set(config.rootExport, config.kind)
-
-        // For JSX lookups (e.g., ClientOnlyJSX), we only need the knownRootImports
-        // fast path to verify imports. Skip module resolution which may fail if
-        // the package isn't a direct dependency (e.g., @tanstack/react-router from
-        // within start-plugin-core).
-        if (config.kind !== 'Root') {
-          const setup = LookupSetup[config.kind]
-          if (setup.type === 'jsx') {
-            return
-          }
-        }
+    // Register start-client-core exports for internal package usage (e.g., react-start-rsc).
+    // These don't need module resolution - only the knownRootImports fast path.
+    this.knownRootImports.set(
+      '@tanstack/start-client-core',
+      new Map<string, Kind>([
+        ['createIsomorphicFn', 'IsomorphicFn'],
+        ['createServerOnlyFn', 'ServerOnlyFn'],
+        ['createClientOnlyFn', 'ClientOnlyFn'],
+      ]),
+    )
 
-        const libId = await this.resolveIdCached(config.libName)
-        if (!libId) {
-          throw new Error(`could not resolve "${config.libName}"`)
-        }
-        let rootModule = this.moduleCache.get(libId)
-        if (!rootModule) {
-          // insert root binding
-          rootModule = {
-            bindings: new Map(),
-            exports: new Map(),
-            id: libId,
-            reExportAllSources: [],
-          }
-          this.moduleCache.set(libId, rootModule)
+    for (const config of this.options.lookupConfigurations) {
+      // Populate the fast lookup map for direct imports (by package name)
+      // This allows O(1) recognition of imports from known packages.
+      let libExports = this.knownRootImports.get(config.libName)
+      if (!libExports) {
+        libExports = new Map()
+        this.knownRootImports.set(config.libName, libExports)
+      }
+      libExports.set(config.rootExport, config.kind)
+
+      // For JSX lookups (e.g., ClientOnlyJSX), we only need the knownRootImports
+      // fast path to verify imports. Skip synthetic root module setup.
+      if (config.kind !== 'Root') {
+        const setup = LookupSetup[config.kind]
+        if (setup.type === 'jsx') {
+          continue
         }
+      }
 
-        rootModule.exports.set(config.rootExport, config.rootExport)
-        rootModule.exports.set('*', config.rootExport)
-        rootModule.bindings.set(config.rootExport, {
-          type: 'var',
-          init: null, // Not needed since resolvedKind is set
-          resolvedKind: config.kind satisfies Kind,
-        })
+      // Root lookup metadata is synthetic package-level state, not a real
+      // resolved module. Keep the ID stable across bundlers and export-map
+      // behavior by always keying it to the package specifier itself.
+      const libId = config.libName
+
+      let rootModule = this.moduleCache.get(libId)
+      if (!rootModule) {
+        // insert root binding
+        rootModule = {
+          bindings: new Map(),
+          exports: new Map(),
+          id: libId,
+          reExportAllSources: [],
+        }
         this.moduleCache.set(libId, rootModule)
-      }),
-    )
+      }
+
+      rootModule.exports.set(config.rootExport, config.rootExport)
+      rootModule.exports.set('*', config.rootExport)
+      rootModule.bindings.set(config.rootExport, {
+        type: 'var',
+        init: null, // Not needed since resolvedKind is set
+        resolvedKind: config.kind satisfies Kind,
+      })
+      this.moduleCache.set(libId, rootModule)
+    }
 
     this.initialized = true
   }

package/src/start-compiler/config.ts

@@ -0,0 +1,73 @@
+import { KindDetectionPatterns, LookupKindsPerEnv } from './compiler'
+import type { LookupConfig, LookupKind } from './compiler'
+import type { CompileStartFrameworkOptions } from '../types'
+
+export function getTransformCodeFilterForEnv(
+  env: 'client' | 'server',
+): Array<RegExp> {
+  const validKinds = LookupKindsPerEnv[env]
+  const patterns: Array<RegExp> = []
+
+  for (const [kind, pattern] of Object.entries(KindDetectionPatterns) as Array<
+    [LookupKind, RegExp]
+  >) {
+    if (validKinds.has(kind)) {
+      patterns.push(pattern)
+    }
+  }
+
+  return patterns
+}
+
+export function getLookupConfigurationsForEnv(
+  env: 'client' | 'server',
+  framework: CompileStartFrameworkOptions,
+): Array<LookupConfig> {
+  const commonConfigs: Array<LookupConfig> = [
+    {
+      libName: `@tanstack/${framework}-start`,
+      rootExport: 'createServerFn',
+      kind: 'Root',
+    },
+    {
+      libName: `@tanstack/${framework}-start`,
+      rootExport: 'createIsomorphicFn',
+      kind: 'IsomorphicFn',
+    },
+    {
+      libName: `@tanstack/${framework}-start`,
+      rootExport: 'createServerOnlyFn',
+      kind: 'ServerOnlyFn',
+    },
+    {
+      libName: `@tanstack/${framework}-start`,
+      rootExport: 'createClientOnlyFn',
+      kind: 'ClientOnlyFn',
+    },
+  ]
+
+  if (env === 'client') {
+    return [
+      {
+        libName: `@tanstack/${framework}-start`,
+        rootExport: 'createMiddleware',
+        kind: 'Root',
+      },
+      {
+        libName: `@tanstack/${framework}-start`,
+        rootExport: 'createStart',
+        kind: 'Root',
+      },
+      ...commonConfigs,
+    ]
+  }
+
+  return [
+    ...commonConfigs,
+    {
+      libName: `@tanstack/${framework}-router`,
+      rootExport: 'ClientOnly',
+      kind: 'ClientOnlyJSX',
+    },
+  ]
+}

package/src/{start-compiler-plugin → start-compiler}/handleCreateServerFn.ts

@@ -1,7 +1,6 @@
 import * as t from '@babel/types'
 import babel from '@babel/core'
 import path from 'pathe'
-import { VITE_ENVIRONMENT_NAMES } from '../constants'
 import { cleanId, codeFrameError, stripMethodCall } from './utils'
 import type { CompilationContext, RewriteCandidate, ServerFn } from './types'
 import type { CompileStartFrameworkOptions } from '../types'
@@ -22,16 +21,11 @@ const clientRpcTemplate = babel.template.expression(
   `createClientRpc(%%functionId%%)`,
 )
 
-// Template for SSR caller files (manifest lookup): createSsrRpc(functionId)
+// Template for SSR caller files: createSsrRpc(functionId)
 const ssrRpcManifestTemplate = babel.template.expression(
   `createSsrRpc(%%functionId%%)`,
 )
 
-// Template for SSR caller files (with importer): createSsrRpc(functionId, () => import(...).then(m => m['name']))
-const ssrRpcImporterTemplate = babel.template.expression(
-  `createSsrRpc(%%functionId%%, () => import(%%extractedFilename%%).then(m => m[%%functionName%%]))`,
-)
-
 // ============================================================================
 // Runtime code cache (cached per framework to avoid repeated AST generation)
 // ============================================================================
@@ -75,8 +69,6 @@ function getCachedRuntimeCode(
 interface EnvConfig {
   /** Whether this environment is a client environment */
   isClientEnvironment: boolean
-  /** Whether SSR is the provider environment */
-  ssrIsProvider: boolean
   /** The runtime code type to use for imports */
   runtimeCodeType: RuntimeCodeType
 }
@@ -88,15 +80,11 @@ function getEnvConfig(
   context: CompilationContext,
   isProviderFile: boolean,
 ): EnvConfig {
-  const { providerEnvName, env } = context
-
-  // SSR is the provider when the provider environment is the default server environment
-  const ssrIsProvider = providerEnvName === VITE_ENVIRONMENT_NAMES.server
+  const { env } = context
 
   if (isProviderFile) {
     return {
       isClientEnvironment: false,
-      ssrIsProvider,
       runtimeCodeType: 'provider',
     }
   }
@@ -104,7 +92,6 @@ function getEnvConfig(
   if (env === 'client') {
     return {
       isClientEnvironment: true,
-      ssrIsProvider,
       runtimeCodeType: 'client',
     }
   }
@@ -112,7 +99,6 @@ function getEnvConfig(
   // Server caller (SSR)
   return {
     isClientEnvironment: false,
-    ssrIsProvider,
     runtimeCodeType: 'ssr',
   }
 }
@@ -154,9 +140,6 @@ function generateProviderRpcStub(
  */
 function generateCallerRpcStub(
   functionId: string,
-  functionName: string,
-  extractedFilename: string,
-  isClientReferenced: boolean,
   envConfig: EnvConfig,
 ): t.Expression {
   const functionIdLiteral = t.stringLiteral(functionId)
@@ -167,20 +150,8 @@ function generateCallerRpcStub(
     })
   }
 
-  // SSR caller
-  // When the function is client-referenced, it's in the manifest - use manifest lookup
-  // When SSR is NOT the provider, always use manifest lookup (no import() for different env)
-  // Otherwise, use the importer for functions only referenced on the server when SSR is the provider
-  if (isClientReferenced || !envConfig.ssrIsProvider) {
-    return ssrRpcManifestTemplate({
-      functionId: functionIdLiteral,
-    })
-  }
-
-  return ssrRpcImporterTemplate({
+  return ssrRpcManifestTemplate({
     functionId: functionIdLiteral,
-    extractedFilename: t.stringLiteral(extractedFilename),
-    functionName: t.stringLiteral(functionName),
   })
 }
 
@@ -262,7 +233,15 @@ export function handleCreateServerFn(
 
     // Check if this function was already discovered by the client build
     const knownFn = knownFns[functionId]
-    const isClientReferenced = envConfig.isClientEnvironment || !!knownFn
+    // A server function is client-referenced when:
+    // 1. We're in the client (browser) environment, OR
+    // 2. It was already discovered by another environment (knownFn), OR
+    // 3. We're in an SSR caller environment — any server function reachable from
+    //    SSR module graph is callable via client navigation HTTP requests
+    const isClientReferenced =
+      envConfig.isClientEnvironment ||
+      !!knownFn ||
+      envConfig.runtimeCodeType === 'ssr'
 
     // Use canonical extracted filename from known functions if available
     const canonicalExtractedFilename =
@@ -395,7 +374,7 @@ export function handleCreateServerFn(
       // Expected output format:
       // const myFn = createServerFn().handler(createClientRpc("id"))
       // or
-      // const myFn = createServerFn().handler(createSsrRpc("id", () => import(...)))
+      // const myFn = createServerFn().handler(createSsrRpc("id"))
 
       // If the handler function is an identifier, we need to remove the bound function
       // from the file since it won't be needed
@@ -408,13 +387,7 @@ export function handleCreateServerFn(
 
       // Generate the RPC stub using pre-compiled templates
       // Note: Caller files only pass functionId, not the full serverFnMeta
-      const rpcStub = generateCallerRpcStub(
-        functionId,
-        functionName,
-        canonicalExtractedFilename,
-        isClientReferenced,
-        envConfig,
-      )
+      const rpcStub = generateCallerRpcStub(functionId, envConfig)
 
       // Replace ONLY the handler argument with the RPC stub
       // Keep the createServerFn().handler() wrapper intact for client middleware

package/src/start-compiler/host.ts

@@ -0,0 +1,80 @@
+import { LookupKindsPerEnv, StartCompiler } from './compiler'
+import { getLookupConfigurationsForEnv } from './config'
+import type { CompileStartFrameworkOptions } from '../types'
+import type {
+  DevServerFnModuleSpecifierEncoder,
+  GenerateFunctionIdFnOptional,
+  ServerFn,
+} from './types'
+
+export interface CreateStartCompilerOptions {
+  env: 'client' | 'server'
+  envName: string
+  root: string
+  framework: CompileStartFrameworkOptions
+  providerEnvName: string
+  mode: 'dev' | 'build'
+  generateFunctionId?: GenerateFunctionIdFnOptional
+  onServerFnsById?: (d: Record<string, ServerFn>) => void
+  getKnownServerFns?: () => Record<string, ServerFn>
+  encodeModuleSpecifierInDev?: DevServerFnModuleSpecifierEncoder
+  loadModule: (id: string) => Promise<void>
+  resolveId: (id: string, importer?: string) => Promise<string | null>
+}
+
+export function createStartCompiler(
+  options: CreateStartCompilerOptions,
+): StartCompiler {
+  return new StartCompiler({
+    env: options.env,
+    envName: options.envName,
+    root: options.root,
+    lookupKinds: LookupKindsPerEnv[options.env],
+    lookupConfigurations: getLookupConfigurationsForEnv(
+      options.env,
+      options.framework,
+    ),
+    mode: options.mode,
+    framework: options.framework,
+    providerEnvName: options.providerEnvName,
+    generateFunctionId: options.generateFunctionId,
+    onServerFnsById: options.onServerFnsById,
+    getKnownServerFns: options.getKnownServerFns,
+    devServerFnModuleSpecifierEncoder: options.encodeModuleSpecifierInDev,
+    loadModule: options.loadModule,
+    resolveId: options.resolveId,
+  })
+}
+
+export function mergeServerFnsById(
+  current: Record<string, ServerFn>,
+  next: Record<string, ServerFn>,
+): void {
+  for (const [id, fn] of Object.entries(next)) {
+    const existing = current[id]
+
+    if (existing) {
+      current[id] = {
+        ...fn,
+        isClientReferenced:
+          existing.isClientReferenced || fn.isClientReferenced,
+      }
+      continue
+    }
+
+    current[id] = fn
+  }
+}
+
+export function matchesCodeFilters(
+  code: string,
+  filters: ReadonlyArray<RegExp>,
+): boolean {
+  for (const pattern of filters) {
+    if (pattern.test(code)) {
+      return true
+    }
+  }
+
+  return false
+}

package/src/start-compiler/load-module.ts

@@ -0,0 +1,31 @@
+import { SERVER_FN_LOOKUP } from '../constants'
+import type { StartCompiler } from './compiler'
+
+interface ViteCompilerModuleLoaderOptions {
+  compiler: StartCompiler
+  mode: string
+  fetchModule?: (id: string) => Promise<unknown>
+  loadModule: (opts: { id: string }) => Promise<{ code?: string | null }>
+  id: string
+}
+
+export async function loadModuleForViteCompiler(
+  opts: ViteCompilerModuleLoaderOptions,
+): Promise<void> {
+  if (opts.mode === 'build') {
+    const loaded = await opts.loadModule({ id: opts.id })
+    const code = loaded.code ?? ''
+
+    opts.compiler.ingestModule({ code, id: opts.id })
+
+    return
+  }
+
+  if (opts.mode !== 'dev' || !opts.fetchModule) {
+    throw new Error(
+      `could not load module ${opts.id}: unknown environment mode ${opts.mode}`,
+    )
+  }
+
+  await opts.fetchModule(`${opts.id}?${SERVER_FN_LOOKUP}`)
+}

package/src/start-compiler/server-fn-resolver-module.ts

@@ -0,0 +1,129 @@
+import type { ServerFn } from './types'
+
+interface ResolverManifestEntry {
+  id: string
+  functionName: string
+  extractedFilename: string
+  isClientReferenced: boolean
+}
+
+interface GenerateServerFnResolverModuleOptions {
+  serverFnsById: Record<string, ServerFn>
+  includeClientReferencedCheck: boolean
+  useStaticImports?: boolean
+}
+
+function getResolverManifestEntries(
+  serverFnsById: Record<string, ServerFn>,
+): Array<ResolverManifestEntry> {
+  return Object.entries(serverFnsById).map(([id, fn]) => ({
+    id,
+    functionName: fn.functionName,
+    extractedFilename: fn.extractedFilename,
+    isClientReferenced: fn.isClientReferenced ?? true,
+  }))
+}
+
+function getClientReferencedCheck(
+  includeClientReferencedCheck: boolean,
+): string {
+  if (!includeClientReferencedCheck) {
+    return ''
+  }
+
+  return `
+  if (access.origin === 'client' && !serverFnInfo.isClientReferenced) {
+    throw new Error('Server function not accessible from client: ' + id)
+  }
+`
+}
+
+function getResolverBody(): string {
+  return `
+export async function getServerFnById(id, access) {
+  const serverFnInfo = manifest[id]
+  if (!serverFnInfo) {
+    throw new Error('Server function info not found for ' + id)
+  }
+__CLIENT_REFERENCED_CHECK__
+  const fnModule = serverFnInfo.module ?? (await serverFnInfo.importer())
+  if (!fnModule) {
+    throw new Error('Server function module not resolved for ' + id)
+  }
+  const action = fnModule[serverFnInfo.functionName]
+  if (!action) {
+    throw new Error('Server function module export not resolved for serverFn ID: ' + id)
+  }
+  return action
+}
+`
+}
+
+function getResolverManifestModuleAccess(opts: {
+  useStaticImports?: boolean
+  extractedFilename: string
+  moduleRef: string
+}): string {
+  if (opts.useStaticImports) {
+    return `module: ${opts.moduleRef}`
+  }
+
+  return `importer: () => import(${JSON.stringify(opts.extractedFilename)})`
+}
+
+function getResolverManifestEntry(opts: {
+  entry: ResolverManifestEntry
+  moduleAccess: string
+  includeClientReferencedCheck: boolean
+}): string {
+  const clientReferenced = opts.includeClientReferencedCheck
+    ? `,\n    isClientReferenced: ${opts.entry.isClientReferenced}`
+    : ''
+
+  return `'${opts.entry.id}': {
+    functionName: '${opts.entry.functionName}',
+    ${opts.moduleAccess}${clientReferenced}
+  }`
+}
+
+export function generateServerFnResolverModule(
+  opts: GenerateServerFnResolverModuleOptions,
+): string {
+  const manifestEntries = getResolverManifestEntries(opts.serverFnsById)
+  const staticImports: Array<string> = []
+
+  const manifest = manifestEntries
+    .map((entry, index) => {
+      const moduleRef = `serverFnModule${index}`
+
+      if (opts.useStaticImports) {
+        staticImports.push(
+          `import * as ${moduleRef} from ${JSON.stringify(entry.extractedFilename)}`,
+        )
+      }
+
+      return getResolverManifestEntry({
+        entry,
+        moduleAccess: getResolverManifestModuleAccess({
+          useStaticImports: opts.useStaticImports,
+          extractedFilename: entry.extractedFilename,
+          moduleRef,
+        }),
+        includeClientReferencedCheck: opts.includeClientReferencedCheck,
+      })
+    })
+    .join(',\n  ')
+
+  const body = getResolverBody().replace(
+    '__CLIENT_REFERENCED_CHECK__',
+    getClientReferencedCheck(opts.includeClientReferencedCheck),
+  )
+
+  return `
+${staticImports.join('\n')}
+const manifest = {
+  ${manifest}
+}
+${body}
+`
+}

package/src/{start-compiler-plugin → start-compiler}/types.ts

@@ -112,6 +112,11 @@ export type GenerateFunctionIdFnOptional = (
  * Function type for generating replacement code for server functions.
  * Used internally by handleCreateServerFn.
  */
+export type DevServerFnModuleSpecifierEncoder = (opts: {
+  extractedFilename: string
+  root: string
+}) => string
+
 export type ReplacerFn = (opts: {
   /** Placeholder for the original function expression */
   fn: string