@tanstack/start-plugin-core 1.167.17 → 1.167.19

package/src/{prerender.ts → vite/prerender.ts}

@@ -2,11 +2,11 @@ import { promises as fsp } from 'node:fs'
 import os from 'node:os'
 import path from 'pathe'
 import { joinURL, withBase, withTrailingSlash, withoutBase } from 'ufo'
-import { VITE_ENVIRONMENT_NAMES } from './constants'
-import { createLogger } from './utils'
-import { Queue } from './queue'
+import { VITE_ENVIRONMENT_NAMES } from '../constants'
+import { createLogger } from '../utils'
+import { Queue } from '../queue'
 import type { PreviewServer, ResolvedConfig, ViteBuilder } from 'vite'
-import type { Page, TanStackStartOutputConfig } from './schema'
+import type { Page, TanStackStartOutputConfig } from '../schema'
 
 export async function prerender({
   startConfig,
@@ -18,13 +18,10 @@ export async function prerender({
   const logger = createLogger('prerender')
   logger.info('Prerendering pages...')
 
-  // If prerender is enabled
   if (startConfig.prerender?.enabled) {
-    // default to root page if no pages are defined
     let pages = startConfig.pages.length ? startConfig.pages : [{ path: '/' }]
 
     if (startConfig.prerender.autoStaticPathsDiscovery ?? true) {
-      // merge discovered static pages with user-defined pages
       const pagesMap = new Map(pages.map((item) => [item.path, item]))
       const discoveredPages = globalThis.TSS_PRERENDABLE_PATHS || []
 
@@ -43,7 +40,6 @@ export async function prerender({
   const routerBasePath = joinURL('/', startConfig.router.basepath ?? '')
   const routerBaseUrl = new URL(routerBasePath, 'http://localhost')
 
-  // Enforce that prerender page paths are relative/path-based (no protocol/host)
   startConfig.pages = validateAndNormalizePrerenderPages(
     startConfig.pages,
     routerBaseUrl,
@@ -69,13 +65,13 @@ export async function prerender({
   process.env.TSS_PRERENDERING = 'true'
   process.env.TSS_CLIENT_OUTPUT_DIR = outputDir
 
-  // Start Vite preview server instead of importing module
   const previewServer = await startPreviewServer(serverEnv.config)
   const baseUrl = getResolvedUrl(previewServer)
 
   const isRedirectResponse = (res: Response) => {
     return res.status >= 300 && res.status < 400 && res.headers.get('location')
   }
+
   async function localFetch(
     path: string,
     options?: RequestInit,
@@ -90,16 +86,15 @@ export async function prerender({
       if (location.startsWith('http://localhost') || location.startsWith('/')) {
         const newUrl = location.replace('http://localhost', '')
         return localFetch(newUrl, options, maxRedirects - 1)
-      } else {
-        logger.warn(`Skipping redirect to external location: ${location}`)
       }
+
+      logger.warn(`Skipping redirect to external location: ${location}`)
     }
 
     return response
   }
 
   try {
-    // Crawl all pages
     const pages = await prerenderPages({ outputDir })
 
     logger.info(`Prerendered ${pages.length} pages:`)
@@ -115,7 +110,7 @@ export async function prerender({
   function extractLinks(html: string): Array<string> {
     const linkRegex = /<a[^>]+href=["']([^"']+)["'][^>]*>/g
     const links: Array<string> = []
-    let match
+    let match: RegExpExecArray | null
 
     while ((match = linkRegex.exec(html)) !== null) {
       const href = match[1]
@@ -136,7 +131,6 @@ export async function prerender({
     const queue = new Queue({ concurrency })
     const routerBasePath = joinURL('/', startConfig.router.basepath ?? '')
 
-    // Normalize discovered pages and enforce path-only entries
     const routerBaseUrl = new URL(routerBasePath, 'http://localhost')
     startConfig.pages = validateAndNormalizePrerenderPages(
       startConfig.pages,
@@ -155,36 +149,32 @@ export async function prerender({
     return Array.from(prerendered)
 
     function addCrawlPageTask(page: Page) {
-      // Was the page already seen?
       if (seen.has(page.path)) return
 
-      // Add the page to the seen set
       seen.add(page.path)
 
       if (page.fromCrawl) {
         startConfig.pages.push(page)
       }
 
-      // If not enabled, skip
       if (!(page.prerender?.enabled ?? true)) return
 
-      // If there is a filter link, check if the page should be prerendered
-      if (startConfig.prerender?.filter && !startConfig.prerender.filter(page))
+      if (
+        startConfig.prerender?.filter &&
+        !startConfig.prerender.filter(page)
+      ) {
         return
+      }
 
-      // Resolve the merged default and page-specific prerender options
       const prerenderOptions = {
         ...startConfig.prerender,
         ...page.prerender,
       }
 
-      // Add the task
       queue.add(async () => {
         logger.info(`Crawling: ${page.path}`)
         const retries = retriesByPath.get(page.path) || 0
         try {
-          // Fetch the route
-
           const res = await localFetch(
             withTrailingSlash(withBase(page.path, routerBasePath)),
             {
@@ -208,7 +198,6 @@ export async function prerender({
             prerenderOptions.outputPath || page.path
           ).split(/[?#]/)[0]!
 
-          // Guess route type and populate fileName
           const contentType = res.headers.get('content-type') || ''
           const isImplicitHTML =
             !cleanPagePath.endsWith('.html') && contentType.includes('html')
@@ -222,17 +211,14 @@ export async function prerender({
 
           let htmlPath: string
           if (isSpaShell) {
-            // For SPA shell, ignore autoSubfolderIndex option
             htmlPath = cleanPagePath + '.html'
+          } else if (
+            cleanPagePath.endsWith('/') ||
+            (prerenderOptions.autoSubfolderIndex ?? true)
+          ) {
+            htmlPath = joinURL(cleanPagePath, 'index.html')
           } else {
-            if (
-              cleanPagePath.endsWith('/') ||
-              (prerenderOptions.autoSubfolderIndex ?? true)
-            ) {
-              htmlPath = joinURL(cleanPagePath, 'index.html')
-            } else {
-              htmlPath = cleanPagePath + '.html'
-            }
+            htmlPath = cleanPagePath + '.html'
           }
 
           const filename = withoutBase(
@@ -258,7 +244,6 @@ export async function prerender({
             Object.assign(page, newPage)
           }
 
-          // Find new links
           if (prerenderOptions.crawlLinks ?? true) {
             const links = extractLinks(html)
             for (const link of links) {
@@ -273,10 +258,8 @@ export async function prerender({
             )
             retriesByPath.set(page.path, retries + 1)
             addCrawlPageTask(page)
-          } else {
-            if (prerenderOptions.failOnError ?? true) {
-              throw error
-            }
+          } else if (prerenderOptions.failOnError ?? true) {
+            throw error
           }
         }
       })
@@ -317,11 +300,6 @@ function getResolvedUrl(previewServer: PreviewServer): URL {
   return new URL(baseUrl)
 }
 
-/**
- * Validates and normalizes prerender page paths to ensure they are relative
- * (no protocol/host) and returns normalized Page objects with cleaned paths.
- * Preserves unicode characters by decoding the pathname after URL validation.
- */
 function validateAndNormalizePrerenderPages(
   pages: Array<Page>,
   routerBaseUrl: URL,
@@ -340,9 +318,6 @@ function validateAndNormalizePrerenderPages(
       throw new Error(`prerender page path must be relative: ${page.path}`)
     }
 
-    // Decode the pathname to preserve unicode characters (e.g., /대한민국)
-    // The URL constructor encodes non-ASCII characters, but we want to keep
-    // the original unicode form for filesystem paths
     const decodedPathname = decodeURIComponent(url.pathname)
 
     return {

package/src/{preview-server-plugin → vite/preview-server-plugin}/plugin.ts

@@ -2,9 +2,9 @@ import { pathToFileURL } from 'node:url'
 import { basename, extname, join } from 'pathe'
 import { NodeRequest, sendNodeResponse } from 'srvx/node'
 import { joinURL } from 'ufo'
-import { VITE_ENVIRONMENT_NAMES } from '../constants'
+import { VITE_ENVIRONMENT_NAMES } from '../../constants'
 import { getServerOutputDirectory } from '../output-directory'
-import { getBundlerOptions } from '../utils'
+import { getBundlerOptions } from '../../utils'
 import type { Plugin } from 'vite'
 
 export function previewServerPlugin(): Plugin {

package/src/vite/schema.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod'
+import {
+  parseStartConfig as parseCoreStartConfig,
+  tanstackStartOptionsObjectSchema,
+} from '../schema'
+import type { CompileStartFrameworkOptions } from '../types'
+
+export const tanstackStartViteOptionsSchema = tanstackStartOptionsObjectSchema
+  .extend({
+    vite: z
+      .object({ installDevServerMiddleware: z.boolean().optional() })
+      .optional(),
+  })
+  .optional()
+  .default({})
+
+export function parseStartConfig(
+  opts: z.input<typeof tanstackStartViteOptionsSchema>,
+  corePluginOpts: { framework: CompileStartFrameworkOptions },
+  root: string,
+) {
+  const { vite: _vite, ...coreOptions } =
+    tanstackStartViteOptionsSchema.parse(opts)
+
+  return parseCoreStartConfig(coreOptions, corePluginOpts, root)
+}
+
+export type TanStackStartViteInputConfig = z.input<
+  typeof tanstackStartViteOptionsSchema
+>

package/src/vite/serialization-adapters-plugin.ts

@@ -0,0 +1,69 @@
+import { VIRTUAL_MODULES } from '@tanstack/start-server-core'
+import {
+  EMPTY_SERIALIZATION_ADAPTERS_MODULE,
+  generateSerializationAdaptersModule,
+} from '../serialization-adapters-module'
+import { START_ENVIRONMENT_NAMES } from '../constants'
+import { resolveViteId } from '../utils'
+import type { SerializationAdapterConfig } from '../types'
+import type { PluginOption } from 'vite'
+
+// 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 resolvedModuleId = resolveViteId(
+  VIRTUAL_MODULES.pluginAdapters.replace('#', '%23'),
+)
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\#]/g, '\\$&')
+}
+
+export function serializationAdaptersPlugin(opts: {
+  adapters: Array<SerializationAdapterConfig> | undefined
+}): PluginOption {
+  return {
+    name: 'tanstack-start:plugin-adapters',
+    enforce: 'pre',
+    resolveId: {
+      filter: { id: new RegExp(escapeRegex(VIRTUAL_MODULES.pluginAdapters)) },
+      handler(id: string) {
+        if (id === VIRTUAL_MODULES.pluginAdapters) {
+          return resolvedModuleId
+        }
+        return undefined
+      },
+    },
+    load: {
+      filter: {
+        id: new RegExp(escapeRegex(resolvedModuleId)),
+      },
+      handler(this: { environment: { name: string } }, id: string) {
+        if (id !== resolvedModuleId) {
+          return undefined
+        }
+
+        const adapters = opts.adapters
+        if (!adapters || adapters.length === 0) {
+          return EMPTY_SERIALIZATION_ADAPTERS_MODULE
+        }
+
+        if (this.environment.name === START_ENVIRONMENT_NAMES.client) {
+          return generateSerializationAdaptersModule({
+            adapters,
+            runtime: 'client',
+          })
+        }
+
+        if (this.environment.name === START_ENVIRONMENT_NAMES.server) {
+          return generateSerializationAdaptersModule({
+            adapters,
+            runtime: 'server',
+          })
+        }
+
+        return EMPTY_SERIALIZATION_ADAPTERS_MODULE
+      },
+    },
+  }
+}

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

@@ -0,0 +1,31 @@
+import type { DevServerFnModuleSpecifierEncoder } from '../../start-compiler/types'
+
+export function createViteDevServerFnModuleSpecifierEncoder(
+  root: string,
+): DevServerFnModuleSpecifierEncoder {
+  const rootWithTrailingSlash = root.endsWith('/') ? root : `${root}/`
+
+  return ({ extractedFilename }) => {
+    let file = extractedFilename
+
+    if (file.startsWith(rootWithTrailingSlash)) {
+      file = file.slice(rootWithTrailingSlash.length)
+    }
+
+    return `/@id/${file}`
+  }
+}
+
+export function decodeViteDevServerModuleSpecifier(
+  moduleSpecifier: string,
+): string {
+  let sourceFile = moduleSpecifier
+
+  if (sourceFile.startsWith('/@id/')) {
+    sourceFile = sourceFile.slice('/@id/'.length)
+  }
+
+  const queryIndex = sourceFile.indexOf('?')
+
+  return queryIndex === -1 ? sourceFile : sourceFile.slice(0, queryIndex)
+}

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

@@ -0,0 +1,345 @@
+import assert from 'node:assert'
+import { VIRTUAL_MODULES } from '@tanstack/start-server-core'
+import { resolve as resolvePath } from 'pathe'
+import {
+  SERVER_FN_LOOKUP,
+  TRANSFORM_ID_REGEX,
+  VITE_ENVIRONMENT_NAMES,
+} from '../../constants'
+import { detectKindsInCode } from '../../start-compiler/compiler'
+import { getTransformCodeFilterForEnv } from '../../start-compiler/config'
+import {
+  createStartCompiler,
+  mergeServerFnsById,
+} from '../../start-compiler/host'
+import { loadModuleForViteCompiler } from '../../start-compiler/load-module'
+import { generateServerFnResolverModule } from '../../start-compiler/server-fn-resolver-module'
+import { cleanId } from '../../start-compiler/utils'
+import {
+  createViteDevServerFnModuleSpecifierEncoder,
+  decodeViteDevServerModuleSpecifier,
+} from './module-specifier'
+import type { CompileStartFrameworkOptions } from '../../types'
+import type {
+  GenerateFunctionIdFnOptional,
+  ServerFn,
+} from '../../start-compiler/types'
+import type { PluginOption } from 'vite'
+
+// Re-export from shared constants for backwards compatibility
+export { SERVER_FN_LOOKUP }
+
+function resolveViteId(id: string) {
+  return `\0${id}`
+}
+
+const validateServerFnIdVirtualModule = `virtual:tanstack-start-validate-server-fn-id`
+
+function getDevServerFnValidatorModule(): string {
+  return `
+export async function getServerFnById(id, _access) {
+  const validateIdImport = ${JSON.stringify(validateServerFnIdVirtualModule)} + '?id=' + id
+  await import(/* @vite-ignore */ '/@id/__x00__' + validateIdImport)
+  const decoded = Buffer.from(id, 'base64url').toString('utf8')
+  const devServerFn = JSON.parse(decoded)
+  const mod = await import(/* @vite-ignore */ devServerFn.file)
+  return mod[devServerFn.export]
+}
+`
+}
+
+function parseIdQuery(id: string): {
+  filename: string
+  query: {
+    [k: string]: string
+  }
+} {
+  if (!id.includes('?')) return { filename: id, query: {} }
+  const [filename, rawQuery] = id.split(`?`, 2) as [string, string]
+  const query = Object.fromEntries(new URLSearchParams(rawQuery))
+  return { filename, query }
+}
+
+export interface StartCompilerPluginOptions {
+  framework: CompileStartFrameworkOptions
+  environments: Array<{
+    name: string
+    type: 'client' | 'server'
+    getServerFnById?: string
+  }>
+  /**
+   * Custom function ID generator (optional).
+   */
+  generateFunctionId?: GenerateFunctionIdFnOptional
+  /**
+   * The Vite environment name for the server function provider.
+   */
+  providerEnvName: string
+}
+
+export function startCompilerPlugin(
+  opts: StartCompilerPluginOptions,
+): PluginOption {
+  const compilers = new Map<string, ReturnType<typeof createStartCompiler>>()
+
+  // Shared registry of server functions across all environments
+  const serverFnsById: Record<string, ServerFn> = {}
+
+  const onServerFnsById = (d: Record<string, ServerFn>) => {
+    mergeServerFnsById(serverFnsById, d)
+  }
+
+  let root = process.cwd()
+  const resolvedResolverVirtualImportId = resolveViteId(
+    VIRTUAL_MODULES.serverFnResolver,
+  )
+
+  // Determine which environments need the resolver (getServerFnById)
+  // SSR environment always needs the resolver for server-side calls
+  // Provider environment needs it for the actual implementation
+  const ssrEnvName = VITE_ENVIRONMENT_NAMES.server
+
+  // SSR is the provider when the provider environment is the default server environment
+  const ssrIsProvider = opts.providerEnvName === ssrEnvName
+
+  // Environments that need the resolver: SSR (for server calls) and provider (for implementation)
+  const appliedResolverEnvironments = new Set(
+    ssrIsProvider ? [opts.providerEnvName] : [ssrEnvName, opts.providerEnvName],
+  )
+
+  function perEnvServerFnPlugin(environment: {
+    name: string
+    type: 'client' | 'server'
+  }): PluginOption {
+    // Derive transform code filter from KindDetectionPatterns (single source of truth)
+    const transformCodeFilter = getTransformCodeFilterForEnv(environment.type)
+    return {
+      name: `tanstack-start-core::server-fn:${environment.name}`,
+      enforce: 'pre',
+      applyToEnvironment(env) {
+        return env.name === environment.name
+      },
+      configResolved(config) {
+        root = config.root
+      },
+      transform: {
+        filter: {
+          id: {
+            exclude: new RegExp(`${SERVER_FN_LOOKUP}$`),
+            include: TRANSFORM_ID_REGEX,
+          },
+          code: {
+            include: transformCodeFilter,
+          },
+        },
+        async handler(code, id) {
+          let compiler = compilers.get(this.environment.name)
+
+          if (!compiler) {
+            // Default to 'dev' mode for unknown environments (conservative: no caching)
+            const mode = this.environment.mode === 'build' ? 'build' : 'dev'
+
+            compiler = createStartCompiler({
+              env: environment.type,
+              envName: environment.name,
+              root,
+              mode,
+              framework: opts.framework,
+              providerEnvName: opts.providerEnvName,
+              generateFunctionId: opts.generateFunctionId,
+              onServerFnsById,
+              getKnownServerFns: () => serverFnsById,
+              encodeModuleSpecifierInDev:
+                mode === 'dev'
+                  ? createViteDevServerFnModuleSpecifierEncoder(root)
+                  : undefined,
+              loadModule: async (id: string) => {
+                await loadModuleForViteCompiler({
+                  compiler: compiler!,
+                  mode: this.environment.mode,
+                  fetchModule:
+                    this.environment.mode === 'dev'
+                      ? this.environment.fetchModule.bind(this.environment)
+                      : undefined,
+                  loadModule: this.load.bind(this),
+                  id,
+                })
+              },
+
+              resolveId: async (source: string, importer?: string) => {
+                const r = await this.resolve(source, importer)
+
+                if (r) {
+                  if (!r.external) {
+                    return cleanId(r.id)
+                  }
+                }
+
+                return null
+              },
+            })
+
+            compilers.set(this.environment.name, compiler)
+          }
+
+          // Detect which kinds are present in this file before parsing
+          const detectedKinds = detectKindsInCode(code, environment.type)
+
+          const result = await compiler.compile({
+            id,
+            code,
+            detectedKinds,
+          })
+          return result
+        },
+      },
+
+      hotUpdate(ctx) {
+        const compiler = compilers.get(this.environment.name)
+
+        ctx.modules.forEach((m) => {
+          if (m.id) {
+            const deleted = compiler?.invalidateModule(m.id)
+            if (deleted) {
+              m.importers.forEach((importer) => {
+                if (importer.id) {
+                  compiler?.invalidateModule(importer.id)
+                }
+              })
+            }
+          }
+        })
+      },
+    }
+  }
+
+  return [
+    ...opts.environments.map(perEnvServerFnPlugin),
+    {
+      name: 'tanstack-start-core:capture-server-fn-module-lookup',
+      // we only need this plugin in dev mode
+      apply: 'serve',
+      applyToEnvironment(env) {
+        return !!opts.environments.find((e) => e.name === env.name)
+      },
+      transform: {
+        filter: {
+          id: new RegExp(`${SERVER_FN_LOOKUP}$`),
+        },
+        handler(code, id) {
+          const compiler = compilers.get(this.environment.name)
+          compiler?.ingestModule({ code, id: cleanId(id) })
+        },
+      },
+    },
+    // Validate server function ID in dev mode
+    {
+      name: 'tanstack-start-core:validate-server-fn-id',
+      apply: 'serve',
+      load: {
+        filter: {
+          id: new RegExp(resolveViteId(validateServerFnIdVirtualModule)),
+        },
+        async handler(id) {
+          const parsed = parseIdQuery(id)
+          const fnId = parsed.query.id
+          if (fnId && serverFnsById[fnId]) {
+            return `export {}`
+          }
+
+          // ID not yet registered — the source file may not have been
+          // transformed in this dev session yet (e.g. cold restart with
+          // cached client). Try to decode the ID, discover the source
+          // file, trigger its compilation, and re-check.
+          if (fnId) {
+            try {
+              const decoded = JSON.parse(
+                Buffer.from(fnId, 'base64url').toString('utf8'),
+              )
+              if (
+                typeof decoded.file === 'string' &&
+                typeof decoded.export === 'string'
+              ) {
+                // Use the Vite strategy to decode the module specifier
+                // back to the original source file path.
+                const sourceFile = decodeViteDevServerModuleSpecifier(
+                  decoded.file,
+                )
+
+                if (sourceFile) {
+                  // Resolve to absolute path
+                  const absPath = resolvePath(root, sourceFile)
+
+                  // Trigger transform of the source file in this environment,
+                  // which will compile createServerFn calls and populate
+                  // serverFnsById as a side effect.
+                  // This plugin only runs in dev (apply: 'serve'), so mode
+                  // must be 'dev' — assert to narrow to DevEnvironment.
+                  assert(this.environment.mode === 'dev')
+                  await this.environment.fetchModule(absPath)
+
+                  // Re-check after lazy compilation
+                  if (serverFnsById[fnId]) {
+                    return `export {}`
+                  }
+                }
+              }
+            } catch {
+              // Decoding or fetching failed — fall through to error
+            }
+          }
+
+          this.error(`Invalid server function ID: ${fnId}`)
+        },
+      },
+    },
+    // Manifest plugin for server environments
+    {
+      name: 'tanstack-start-core:server-fn-resolver',
+      enforce: 'pre',
+      applyToEnvironment: (env) => {
+        return appliedResolverEnvironments.has(env.name)
+      },
+      configResolved(config) {
+        root = config.root
+      },
+      resolveId: {
+        filter: { id: new RegExp(VIRTUAL_MODULES.serverFnResolver) },
+        handler() {
+          return resolvedResolverVirtualImportId
+        },
+      },
+      load: {
+        filter: { id: new RegExp(resolvedResolverVirtualImportId) },
+        handler() {
+          if (this.environment.name !== opts.providerEnvName) {
+            const mod = opts.environments.find(
+              (e) => e.name === this.environment.name,
+            )?.getServerFnById
+            if (mod) {
+              return mod
+            } else {
+              this.error(
+                `No getServerFnById implementation found for caller environment: ${this.environment.name}`,
+              )
+            }
+          }
+
+          if (this.environment.mode !== 'build') {
+            return getDevServerFnValidatorModule()
+          }
+
+          // When SSR is the provider, server-only-referenced functions aren't in the manifest,
+          // so no isClientReferenced check is needed.
+          // When SSR is NOT the provider (custom provider env), server-only-referenced
+          // functions ARE in the manifest and need the isClientReferenced check to
+          // block direct client HTTP requests to server-only-referenced functions.
+          return generateServerFnResolverModule({
+            serverFnsById,
+            includeClientReferencedCheck: !ssrIsProvider,
+          })
+        },
+      },
+    },
+  ]
+}