@tanstack/start-plugin-core 1.169.11 → 1.169.13

package/src/start-compiler/config.ts

@@ -1,27 +1,47 @@
-import { KindDetectionPatterns, LookupKindsPerEnv } from './compiler'
-import type { LookupConfig, LookupKind } from './compiler'
-import type { CompileStartFrameworkOptions } from '../types'
+import {
+  KindDetectionPatterns,
+  getExternalLookupKind,
+  getLookupKindsForEnv,
+  isCompilerTransformEnabledForEnv,
+} from './compiler'
+import type { BuiltInLookupKind, LookupConfig } from './compiler'
+import type {
+  CompileStartFrameworkOptions,
+  StartCompilerImportTransform,
+} from '../types'
 
 export function getTransformCodeFilterForEnv(
   env: 'client' | 'server',
+  opts?: {
+    compilerTransforms?: Array<StartCompilerImportTransform> | undefined
+  },
 ): Array<RegExp> {
-  const validKinds = LookupKindsPerEnv[env]
+  const validKinds = getLookupKindsForEnv(env, opts)
   const patterns: Array<RegExp> = []
 
   for (const [kind, pattern] of Object.entries(KindDetectionPatterns) as Array<
-    [LookupKind, RegExp]
+    [BuiltInLookupKind, RegExp]
   >) {
     if (validKinds.has(kind)) {
       patterns.push(pattern)
     }
   }
 
+  for (const transform of opts?.compilerTransforms ?? []) {
+    if (isCompilerTransformEnabledForEnv(transform, env)) {
+      patterns.push(transform.detect)
+    }
+  }
+
   return patterns
 }
 
 export function getLookupConfigurationsForEnv(
   env: 'client' | 'server',
   framework: CompileStartFrameworkOptions,
+  opts?: {
+    compilerTransforms?: Array<StartCompilerImportTransform> | undefined
+  },
 ): Array<LookupConfig> {
   const commonConfigs: Array<LookupConfig> = [
     {
@@ -46,6 +66,20 @@ export function getLookupConfigurationsForEnv(
     },
   ]
 
+  const externalConfigs: Array<LookupConfig> = []
+  for (const transform of opts?.compilerTransforms ?? []) {
+    if (!isCompilerTransformEnabledForEnv(transform, env)) continue
+
+    const kind = getExternalLookupKind(transform)
+    for (const imported of transform.imports) {
+      externalConfigs.push({
+        libName: imported.libName,
+        rootExport: imported.rootExport,
+        kind,
+      })
+    }
+  }
+
   if (env === 'client') {
     return [
       {
@@ -59,10 +93,11 @@ export function getLookupConfigurationsForEnv(
         kind: 'Root',
       },
       ...commonConfigs,
+      ...externalConfigs,
     ]
   }
 
-  return [
+  const serverConfigs: Array<LookupConfig> = [
     ...commonConfigs,
     {
       libName: `@tanstack/${framework}-router`,
@@ -70,4 +105,6 @@ export function getLookupConfigurationsForEnv(
       kind: 'ClientOnlyJSX',
     },
   ]
+
+  return [...serverConfigs, ...externalConfigs]
 }

package/src/start-compiler/handleCreateServerFn.ts

@@ -196,6 +196,13 @@ export function handleCreateServerFn(
   }
 
   const isProviderFile = context.id.includes(TSS_SERVERFN_SPLIT_PARAM)
+  if (isProviderFile && context.serverFnProviderModuleDirectives) {
+    ensureDirectivePrologue(
+      context.ast,
+      context.serverFnProviderModuleDirectives,
+    )
+  }
+
   // Get environment-specific configuration
   const envConfig = getEnvConfig(context, isProviderFile)
 
@@ -504,3 +511,25 @@ function safeRemoveExports(ast: t.File): void {
     return node
   })
 }
+
+function ensureDirectivePrologue(
+  ast: t.File,
+  directiveValues: ReadonlyArray<string>,
+): void {
+  const directives = ast.program.directives
+  const existingDirectives = new Set(
+    directives.map((directive) => directive.value.value),
+  )
+  const missingDirectives: Array<string> = []
+
+  for (const directiveValue of directiveValues) {
+    if (!directiveValue || existingDirectives.has(directiveValue)) continue
+
+    existingDirectives.add(directiveValue)
+    missingDirectives.push(directiveValue)
+  }
+
+  for (let i = missingDirectives.length - 1; i >= 0; i--) {
+    directives.unshift(t.directive(t.directiveLiteral(missingDirectives[i]!)))
+  }
+}

package/src/start-compiler/host.ts

@@ -1,6 +1,9 @@
-import { LookupKindsPerEnv, StartCompiler } from './compiler'
+import { StartCompiler, getLookupKindsForEnv } from './compiler'
 import { getLookupConfigurationsForEnv } from './config'
-import type { CompileStartFrameworkOptions } from '../types'
+import type {
+  CompileStartFrameworkOptions,
+  StartCompilerImportTransform,
+} from '../types'
 import type {
   DevServerFnModuleSpecifierEncoder,
   GenerateFunctionIdFnOptional,
@@ -15,6 +18,8 @@ export interface CreateStartCompilerOptions {
   providerEnvName: string
   mode: 'dev' | 'build'
   generateFunctionId?: GenerateFunctionIdFnOptional
+  compilerTransforms?: Array<StartCompilerImportTransform> | undefined
+  serverFnProviderModuleDirectives?: ReadonlyArray<string> | undefined
   onServerFnsById?: (d: Record<string, ServerFn>) => void
   getKnownServerFns: () => Record<string, ServerFn>
   encodeModuleSpecifierInDev?: DevServerFnModuleSpecifierEncoder
@@ -29,16 +34,21 @@ export function createStartCompiler(
     env: options.env,
     envName: options.envName,
     root: options.root,
-    lookupKinds: LookupKindsPerEnv[options.env],
+    lookupKinds: getLookupKindsForEnv(options.env, {
+      compilerTransforms: options.compilerTransforms,
+    }),
     lookupConfigurations: getLookupConfigurationsForEnv(
       options.env,
       options.framework,
+      { compilerTransforms: options.compilerTransforms },
     ),
     mode: options.mode,
     framework: options.framework,
     providerEnvName: options.providerEnvName,
     generateFunctionId: options.generateFunctionId,
     onServerFnsById: options.onServerFnsById,
+    compilerTransforms: options.compilerTransforms,
+    serverFnProviderModuleDirectives: options.serverFnProviderModuleDirectives,
     getKnownServerFns: options.getKnownServerFns,
     devServerFnModuleSpecifierEncoder: options.encodeModuleSpecifierInDev,
     loadModule: options.loadModule,

package/src/start-compiler/types.ts

@@ -1,28 +1,18 @@
 import type * as babel from '@babel/core'
 import type * as t from '@babel/types'
-import type { CompileStartFrameworkOptions } from '../types'
+import type { StartCompilerTransformContext } from '../types'
 
 /**
  * Context passed to all plugin handlers during compilation.
  * Contains both read-only input data and mutable state that handlers update.
  */
-export interface CompilationContext {
-  readonly ast: t.File
-  readonly code: string
-  readonly id: string
-  readonly env: 'client' | 'server'
-  readonly envName: string
-  readonly mode: 'dev' | 'build'
-  readonly root: string
-  /** The framework being used (e.g., 'react', 'solid') */
-  readonly framework: CompileStartFrameworkOptions
-  /** The Vite environment name for the server function provider */
-  readonly providerEnvName: string
-
+export interface CompilationContext extends StartCompilerTransformContext {
   /** Generate a unique function ID */
   generateFunctionId: GenerateFunctionIdFn
   /** Get known server functions from previous builds (e.g., client build) */
   getKnownServerFns: () => Record<string, ServerFn>
+  /** Module-level directives to add to extracted server function provider files. */
+  serverFnProviderModuleDirectives: ReadonlyArray<string> | undefined
 
   /**
    * Callback when server functions are discovered.
@@ -30,6 +20,7 @@ export interface CompilationContext {
    */
   onServerFnsById: ((d: Record<string, ServerFn>) => void) | undefined
 }
+
 /**
  * Batched plugin handler signature.
  * Receives ALL candidates of a specific kind in one call.

package/src/types.ts

@@ -1,3 +1,5 @@
+import type * as babel from '@babel/core'
+import type * as t from '@babel/types'
 import type { TanStackStartOutputConfig } from './schema'
 
 export type CompileStartFrameworkOptions = 'react' | 'solid' | 'vue'
@@ -20,6 +22,46 @@ export type SerializationAdapterConfig =
   | SerializationAdapterModuleRef
   | SerializationAdapterByRuntime
 
+export type StartCompilerEnvironment = 'client' | 'server'
+
+export interface StartCompilerImportTransformImport {
+  libName: string
+  rootExport: string
+}
+
+export interface StartCompilerTransformCandidate {
+  path: babel.NodePath<t.CallExpression>
+}
+
+export interface StartCompilerTransformContext {
+  readonly ast: t.File
+  readonly code: string
+  readonly id: string
+  readonly env: StartCompilerEnvironment
+  readonly envName: string
+  readonly mode: 'dev' | 'build'
+  readonly root: string
+  readonly framework: CompileStartFrameworkOptions
+  readonly providerEnvName: string
+  readonly types: typeof t
+  parseExpression: (code: string) => t.Expression
+}
+
+export interface StartCompilerImportTransform {
+  name: string
+  environment?:
+    | StartCompilerEnvironment
+    | Array<StartCompilerEnvironment>
+    | undefined
+  imports: Array<StartCompilerImportTransformImport>
+  detect: RegExp
+  order?: 'pre' | 'post' | undefined
+  transform: (
+    candidates: Array<StartCompilerTransformCandidate>,
+    context: StartCompilerTransformContext,
+  ) => void
+}
+
 export interface NormalizedBasePaths {
   publicBase: string
   assetBase: {
@@ -60,6 +102,8 @@ export interface TanStackStartCoreOptions {
   providerEnvironmentName: string
   ssrIsProvider: boolean
   serializationAdapters?: Array<SerializationAdapterConfig> | undefined
+  compilerTransforms?: Array<StartCompilerImportTransform> | undefined
+  serverFnProviderModuleDirectives?: ReadonlyArray<string> | undefined
 }
 
 export interface ResolvedStartConfig {

package/src/vite/index.ts

@@ -3,6 +3,11 @@ export type {
   ViteRscForwardSsrResolverStrategy,
 } from './types'
 export type { TanStackStartViteInputConfig } from './schema'
+export type {
+  StartCompilerImportTransform,
+  StartCompilerTransformCandidate,
+  StartCompilerTransformContext,
+} from '../types'
 export { START_ENVIRONMENT_NAMES, VITE_ENVIRONMENT_NAMES } from '../constants'
 export { createVirtualModule } from './createVirtualModule'
 export { tanStackStartVite } from './plugin'

package/src/vite/plugin.ts

@@ -217,6 +217,9 @@ export function tanStackStartVite(
       environments,
       generateFunctionId:
         normalizedStartPluginOpts.serverFns?.generateFunctionId,
+      compilerTransforms: corePluginOpts.compilerTransforms,
+      serverFnProviderModuleDirectives:
+        corePluginOpts.serverFnProviderModuleDirectives,
       providerEnvName: serverFnProviderEnv,
     }),
     importProtectionPlugin({

package/src/vite/start-compiler-plugin/plugin.ts

@@ -20,7 +20,10 @@ import {
   decodeViteDevServerModuleSpecifier,
 } from './module-specifier'
 import { mergeHotUpdateModules } from './hot-update'
-import type { CompileStartFrameworkOptions } from '../../types'
+import type {
+  CompileStartFrameworkOptions,
+  StartCompilerImportTransform,
+} from '../../types'
 import type {
   GenerateFunctionIdFnOptional,
   ServerFn,
@@ -166,6 +169,8 @@ export interface StartCompilerPluginOptions {
    * Custom function ID generator (optional).
    */
   generateFunctionId?: GenerateFunctionIdFnOptional
+  compilerTransforms?: Array<StartCompilerImportTransform> | undefined
+  serverFnProviderModuleDirectives?: ReadonlyArray<string> | undefined
   /**
    * The Vite environment name for the server function provider.
    */
@@ -202,8 +207,18 @@ export function startCompilerPlugin(
     name: string
     type: 'client' | 'server'
   }): PluginOption {
+    const compilerTransforms =
+      environment.name === opts.providerEnvName
+        ? opts.compilerTransforms
+        : undefined
+    const serverFnProviderModuleDirectives =
+      environment.name === opts.providerEnvName
+        ? opts.serverFnProviderModuleDirectives
+        : undefined
     // Derive transform code filter from KindDetectionPatterns (single source of truth)
-    const transformCodeFilter = getTransformCodeFilterForEnv(environment.type)
+    const transformCodeFilter = getTransformCodeFilterForEnv(environment.type, {
+      compilerTransforms,
+    })
     return {
       name: `tanstack-start-core::server-fn:${environment.name}`,
       enforce: 'pre',
@@ -238,6 +253,8 @@ export function startCompilerPlugin(
               framework: opts.framework,
               providerEnvName: opts.providerEnvName,
               generateFunctionId: opts.generateFunctionId,
+              compilerTransforms,
+              serverFnProviderModuleDirectives,
               onServerFnsById,
               getKnownServerFns: () => serverFnsById,
               encodeModuleSpecifierInDev:
@@ -281,7 +298,9 @@ export function startCompilerPlugin(
           }
 
           // Detect which kinds are present in this file before parsing
-          const detectedKinds = detectKindsInCode(code, environment.type)
+          const detectedKinds = detectKindsInCode(code, environment.type, {
+            compilerTransforms,
+          })
 
           const result = await compiler.compile({
             id,