@tanstack/start-plugin-core 1.167.18 → 1.167.19

package/src/vite/planning.ts

@@ -0,0 +1,234 @@
+import { normalizePath } from 'vite'
+import { join } from 'pathe'
+import { escapePath } from 'tinyglobby'
+import { ENTRY_POINTS, START_ENVIRONMENT_NAMES } from '../constants'
+import { getBundlerOptions } from '../utils'
+import type { CompileStartFrameworkOptions } from '../types'
+import type { ResolvedStartEntryPlan } from '../planning'
+import type * as vite from 'vite'
+
+export interface ViteResolvedEntryAliases {
+  client: string
+  server: string
+  start: string
+  router: string
+  alias: Record<(typeof ENTRY_POINTS)[keyof typeof ENTRY_POINTS], string>
+}
+
+export function createViteResolvedEntryAliases(opts: {
+  entryPaths: ResolvedStartEntryPlan['entryPaths']
+}): ViteResolvedEntryAliases {
+  const client = normalizePath(opts.entryPaths.client)
+  const server = normalizePath(opts.entryPaths.server)
+  const start = normalizePath(opts.entryPaths.start)
+  const router = normalizePath(opts.entryPaths.router)
+
+  return {
+    client,
+    server,
+    start,
+    router,
+    alias: {
+      [ENTRY_POINTS.client]: client,
+      [ENTRY_POINTS.server]: server,
+      [ENTRY_POINTS.start]: start,
+      [ENTRY_POINTS.router]: router,
+    },
+  }
+}
+
+export function createViteConfigPlan(opts: {
+  viteConfig: vite.UserConfig
+  framework: CompileStartFrameworkOptions
+  entryAliases: ViteResolvedEntryAliases
+  clientOutputDirectory: string
+  serverOutputDirectory: string
+  serverFnProviderEnv: string
+  optimizeDepsExclude: Array<string>
+  noExternal: Array<string>
+}) {
+  return {
+    environments: {
+      [START_ENVIRONMENT_NAMES.client]: {
+        consumer: 'client',
+        build: (() => {
+          const bundlerOptions = {
+            input: {
+              index: ENTRY_POINTS.client,
+            },
+          }
+          return {
+            rollupOptions: bundlerOptions,
+            rolldownOptions: bundlerOptions,
+            outDir: opts.clientOutputDirectory,
+          }
+        })(),
+        optimizeDeps: {
+          exclude: opts.optimizeDepsExclude,
+          entries: escapeEntries([
+            opts.entryAliases.client,
+            opts.entryAliases.router,
+          ]),
+        },
+      },
+      [START_ENVIRONMENT_NAMES.server]: {
+        consumer: 'server',
+        build: {
+          ssr: true,
+          ...(() => {
+            const bundlerOptions = {
+              input:
+                getBundlerOptions(
+                  opts.viteConfig.environments?.[START_ENVIRONMENT_NAMES.server]
+                    ?.build,
+                )?.input ?? opts.entryAliases.server,
+            }
+            return {
+              rollupOptions: bundlerOptions,
+              rolldownOptions: bundlerOptions,
+            }
+          })(),
+          outDir: opts.serverOutputDirectory,
+          commonjsOptions: {
+            include: [/node_modules/],
+          },
+          copyPublicDir:
+            opts.viteConfig.environments?.[START_ENVIRONMENT_NAMES.server]
+              ?.build?.copyPublicDir ?? false,
+        },
+        optimizeDeps: {
+          entries: escapeEntries([
+            opts.entryAliases.server,
+            opts.entryAliases.start,
+            opts.entryAliases.router,
+          ]),
+        },
+      },
+      ...(opts.serverFnProviderEnv !== START_ENVIRONMENT_NAMES.server && {
+        [opts.serverFnProviderEnv]: {
+          build: {
+            outDir: join(opts.serverOutputDirectory, opts.serverFnProviderEnv),
+          },
+          optimizeDeps: {
+            entries: escapeEntries([opts.entryAliases.router]),
+          },
+        },
+      }),
+    },
+    resolve: {
+      noExternal: [
+        '@tanstack/start**',
+        `@tanstack/${opts.framework}-start**`,
+        ...opts.noExternal,
+      ],
+      alias: {
+        ...opts.entryAliases.alias,
+      },
+    },
+  } satisfies Pick<vite.UserConfig, 'environments' | 'resolve'>
+}
+
+export function createViteDefineConfig(opts: {
+  command: 'serve' | 'build'
+  mode: string | undefined
+  serverFnBase: string
+  routerBasepath: string
+  spaEnabled: boolean | undefined
+  devSsrStylesEnabled: boolean
+  devSsrStylesBasepath: string
+  staticNodeEnv: boolean
+}) {
+  return {
+    ...defineReplaceEnv('TSS_SERVER_FN_BASE', opts.serverFnBase),
+    ...defineReplaceEnv('TSS_ROUTER_BASEPATH', opts.routerBasepath),
+    ...(opts.command === 'serve'
+      ? defineReplaceEnv('TSS_SHELL', opts.spaEnabled ? 'true' : 'false')
+      : {}),
+    ...defineReplaceEnv(
+      'TSS_DEV_SERVER',
+      opts.command === 'serve' ? 'true' : 'false',
+    ),
+    ...defineReplaceEnv(
+      'TSS_DEV_SSR_STYLES_ENABLED',
+      opts.devSsrStylesEnabled ? 'true' : 'false',
+    ),
+    ...defineReplaceEnv(
+      'TSS_DEV_SSR_STYLES_BASEPATH',
+      opts.devSsrStylesBasepath,
+    ),
+    ...(opts.command === 'build' && opts.staticNodeEnv
+      ? {
+          'process.env.NODE_ENV': JSON.stringify(
+            process.env.NODE_ENV || opts.mode || 'production',
+          ),
+        }
+      : {}),
+  } satisfies NonNullable<vite.UserConfig['define']>
+}
+
+export async function buildStartViteEnvironments(opts: {
+  builder: vite.ViteBuilder
+  providerEnvironmentName: string
+  ssrIsProvider: boolean
+}) {
+  const client = getRequiredBuilderEnvironment(
+    opts.builder,
+    START_ENVIRONMENT_NAMES.client,
+    'Client environment not found',
+  )
+  const server = getRequiredBuilderEnvironment(
+    opts.builder,
+    START_ENVIRONMENT_NAMES.server,
+    'SSR environment not found',
+  )
+
+  if (!client.isBuilt) {
+    await opts.builder.build(client)
+  }
+
+  if (!server.isBuilt) {
+    await opts.builder.build(server)
+  }
+
+  if (opts.ssrIsProvider) {
+    return
+  }
+
+  const providerEnv = getRequiredBuilderEnvironment(
+    opts.builder,
+    opts.providerEnvironmentName,
+    `Provider environment "${opts.providerEnvironmentName}" not found`,
+  )
+
+  if (!providerEnv.isBuilt) {
+    await opts.builder.build(providerEnv)
+  }
+}
+
+function escapeEntries(entries: Array<string>) {
+  return entries.map((entry) => escapePath(entry))
+}
+
+function defineReplaceEnv<TKey extends string, TValue extends string>(
+  key: TKey,
+  value: TValue,
+): { [P in `process.env.${TKey}` | `import.meta.env.${TKey}`]: TValue } {
+  return {
+    [`process.env.${key}`]: JSON.stringify(value),
+    [`import.meta.env.${key}`]: JSON.stringify(value),
+  } as { [P in `process.env.${TKey}` | `import.meta.env.${TKey}`]: TValue }
+}
+
+function getRequiredBuilderEnvironment(
+  builder: vite.ViteBuilder,
+  environmentName: string,
+  errorMessage: string,
+) {
+  const environment = builder.environments[environmentName]
+
+  if (!environment) {
+    throw new Error(errorMessage)
+  }
+
+  return environment
+}

package/src/vite/plugin.ts

@@ -0,0 +1,276 @@
+import { crawlFrameworkPkgs } from 'vitefu'
+import {
+  applyResolvedBaseAndOutput,
+  applyResolvedRouterBasepath,
+  createStartConfigContext,
+} from '../config-context'
+import { START_ENVIRONMENT_NAMES } from '../constants'
+import { importProtectionPlugin } from '../import-protection-plugin/plugin'
+import {
+  createServerFnBasePath,
+  normalizePublicBase,
+  shouldRewriteDevBasepath,
+} from '../planning'
+import { startCompilerPlugin } from './start-compiler-plugin/plugin'
+import { loadEnvPlugin } from './load-env-plugin/plugin'
+import {
+  buildStartViteEnvironments,
+  createViteConfigPlan,
+  createViteDefineConfig,
+  createViteResolvedEntryAliases,
+} from './planning'
+import { devServerPlugin } from './dev-server-plugin/plugin'
+import { previewServerPlugin } from './preview-server-plugin/plugin'
+import {
+  createCaptureClientBuildPlugin,
+  createDevBaseRewritePlugin,
+  createPostBuildPlugin,
+} from './plugins'
+import { parseStartConfig } from './schema'
+import { startManifestPlugin } from './start-manifest-plugin/plugin'
+import { tanStackStartRouter } from './start-router-plugin/plugin'
+import {
+  getClientOutputDirectory,
+  getServerOutputDirectory,
+} from './output-directory'
+import { postServerBuild } from './post-server-build'
+import { serializationAdaptersPlugin } from './serialization-adapters-plugin'
+import type { NormalizedClientBuild } from '../types'
+import type {
+  TanStackStartVitePluginCoreOptions,
+  ViteRscForwardSsrResolverStrategy,
+} from './types'
+import type { StartEnvironmentName } from '../constants'
+import type { TanStackStartViteInputConfig } from './schema'
+import type { PluginOption } from 'vite'
+
+export function tanStackStartVite(
+  corePluginOpts: TanStackStartVitePluginCoreOptions,
+  startPluginOpts: TanStackStartViteInputConfig | undefined,
+): Array<PluginOption> {
+  const normalizedStartPluginOpts = startPluginOpts ?? {}
+
+  const configContext = createStartConfigContext({
+    corePluginOpts,
+    startPluginOpts: normalizedStartPluginOpts,
+    parseConfig: parseStartConfig,
+  })
+  const { getConfig, resolvedStartConfig } = configContext
+  const serverFnProviderEnv = corePluginOpts.providerEnvironmentName
+  const ssrIsProvider = corePluginOpts.ssrIsProvider
+
+  // When the router basepath and vite base are misaligned during dev,
+  // we install a URL rewrite middleware instead of erroring.
+  let needsDevBaseRewrite = false
+
+  const capturedClientBuild: Partial<
+    Record<StartEnvironmentName, NormalizedClientBuild>
+  > = {}
+
+  function getClientBuild(
+    envName: StartEnvironmentName,
+  ): NormalizedClientBuild | undefined {
+    return capturedClientBuild[envName]
+  }
+
+  const environments: Array<{
+    name: string
+    type: 'client' | 'server'
+    getServerFnById?: string
+  }> = [
+    { name: START_ENVIRONMENT_NAMES.client, type: 'client' },
+    {
+      name: START_ENVIRONMENT_NAMES.server,
+      type: 'server',
+      getServerFnById:
+        corePluginOpts.ssrResolverStrategy.type === 'vite-rsc-forward'
+          ? createViteRscForwarder(corePluginOpts.ssrResolverStrategy)
+          : undefined,
+    },
+  ]
+  if (
+    serverFnProviderEnv !== START_ENVIRONMENT_NAMES.server &&
+    !environments.find((e) => e.name === serverFnProviderEnv)
+  ) {
+    environments.push({
+      name: serverFnProviderEnv,
+      type: 'server',
+    })
+  }
+  return [
+    {
+      name: 'tanstack-start-core:config',
+      enforce: 'pre',
+      async config(viteConfig, { command }) {
+        const publicBase = normalizePublicBase(viteConfig.base)
+        applyResolvedBaseAndOutput({
+          resolvedStartConfig,
+          root: viteConfig.root || process.cwd(),
+          publicBase,
+          clientOutputDirectory: getClientOutputDirectory(viteConfig),
+          serverOutputDirectory: getServerOutputDirectory(viteConfig),
+        })
+        const { startConfig } = getConfig()
+        const routerBasepath = applyResolvedRouterBasepath({
+          resolvedStartConfig,
+          startConfig,
+        })
+
+        if (
+          shouldRewriteDevBasepath({
+            command,
+            middlewareMode: Boolean(viteConfig.server?.middlewareMode),
+            routerBasepath,
+            publicBase: resolvedStartConfig.basePaths.publicBase,
+          })
+        ) {
+          // The router basepath and vite base are misaligned.
+          // Instead of erroring, we install a dev-server middleware that
+          // rewrites incoming request URLs to prepend the vite base prefix.
+          // This allows users to have e.g. base: '/_ui/' for asset URLs
+          // while keeping router basepath at '/' for page navigation.
+          needsDevBaseRewrite = true
+        }
+
+        const TSS_SERVER_FN_BASE = createServerFnBasePath({
+          routerBasepath,
+          serverFnBase: startConfig.serverFns.base,
+        })
+        const resolvedEntryPlan = configContext.resolveEntries()
+
+        const entryAliases = createViteResolvedEntryAliases({
+          entryPaths: resolvedEntryPlan.entryPaths,
+        })
+
+        const startPackageName =
+          `@tanstack/${corePluginOpts.framework}-start` as const
+
+        // crawl packages that have start in "peerDependencies"
+        // see https://github.com/svitejs/vitefu/blob/d8d82fa121e3b2215ba437107093c77bde51b63b/src/index.js#L95-L101
+
+        // this is currently uncached; could be implemented similarly as vite handles lock file changes
+        // see https://github.com/vitejs/vite/blob/557f797d29422027e8c451ca50dd84bf8c41b5f0/packages/vite/src/node/optimizer/index.ts#L1282
+
+        const crawlFrameworkPkgsResult = await crawlFrameworkPkgs({
+          root: process.cwd(),
+          isBuild: command === 'build',
+          isFrameworkPkgByJson(pkgJson) {
+            const peerDependencies = pkgJson['peerDependencies']
+
+            if (peerDependencies) {
+              if (
+                startPackageName in peerDependencies ||
+                '@tanstack/start-client-core' in peerDependencies
+              ) {
+                return true
+              }
+            }
+
+            return false
+          },
+        })
+
+        const viteConfigPlan = createViteConfigPlan({
+          viteConfig,
+          framework: corePluginOpts.framework,
+          entryAliases,
+          clientOutputDirectory: resolvedStartConfig.outputDirectories.client,
+          serverOutputDirectory: resolvedStartConfig.outputDirectories.server,
+          serverFnProviderEnv,
+          optimizeDepsExclude: crawlFrameworkPkgsResult.optimizeDeps.exclude,
+          noExternal: crawlFrameworkPkgsResult.ssr.noExternal.sort(),
+        })
+
+        return {
+          // see https://vite.dev/config/shared-options.html#apptype
+          // this will prevent vite from injecting middlewares that we don't want
+          appType: viteConfig.appType ?? 'custom',
+          environments: viteConfigPlan.environments,
+          resolve: viteConfigPlan.resolve,
+          define: createViteDefineConfig({
+            command,
+            mode: viteConfig.mode,
+            serverFnBase: TSS_SERVER_FN_BASE,
+            routerBasepath,
+            spaEnabled: startConfig.spa?.enabled,
+            devSsrStylesEnabled: startConfig.dev.ssrStyles.enabled,
+            devSsrStylesBasepath:
+              startConfig.dev.ssrStyles.basepath ??
+              resolvedStartConfig.basePaths.publicBase,
+            staticNodeEnv: startConfig.server.build.staticNodeEnv,
+          }),
+          builder: {
+            sharedPlugins: true,
+            async buildApp(builder) {
+              await buildStartViteEnvironments({
+                builder,
+                providerEnvironmentName: serverFnProviderEnv,
+                ssrIsProvider,
+              })
+            },
+          },
+        }
+      },
+    },
+    createPostBuildPlugin({
+      getConfig,
+      postServerBuild,
+    }),
+    // Server function plugin handles:
+    // 1. Identifying createServerFn().handler() calls
+    // 2. Extracting server functions to separate modules
+    // 3. Replacing call sites with RPC stubs
+    // 4. Generating the server function manifest
+    // Also handles createIsomorphicFn, createServerOnlyFn, createClientOnlyFn, createMiddleware
+    startCompilerPlugin({
+      framework: corePluginOpts.framework,
+      environments,
+      generateFunctionId:
+        normalizedStartPluginOpts.serverFns?.generateFunctionId,
+      providerEnvName: serverFnProviderEnv,
+    }),
+    importProtectionPlugin({
+      getConfig,
+      framework: corePluginOpts.framework,
+      environments,
+      providerEnvName: serverFnProviderEnv,
+    }),
+    tanStackStartRouter(normalizedStartPluginOpts, getConfig, corePluginOpts),
+    loadEnvPlugin(),
+    startManifestPlugin({
+      getClientBuild: () => getClientBuild(START_ENVIRONMENT_NAMES.client),
+      getConfig,
+    }),
+    // When the vite base and router basepath are misaligned (e.g. base: '/_ui/', basepath: '/'),
+    // install a middleware that rewrites incoming request URLs to prepend the vite base prefix.
+    // This allows Vite's internal base middleware to accept the requests, then strips the prefix
+    // before passing to the SSR handler.
+    // Registered BEFORE devServerPlugin so this middleware is added to the Connect stack first,
+    // ensuring all subsequent middlewares (CSS, SSR, etc.) see the rewritten URL.
+    createDevBaseRewritePlugin({
+      shouldRewriteDevBase: () => needsDevBaseRewrite,
+      resolvedStartConfig,
+    }),
+    devServerPlugin({
+      getConfig,
+      devSsrStylesEnabled:
+        normalizedStartPluginOpts.dev?.ssrStyles?.enabled ?? true,
+      installDevServerMiddleware:
+        normalizedStartPluginOpts.vite?.installDevServerMiddleware,
+    }),
+    previewServerPlugin(),
+    serializationAdaptersPlugin({
+      adapters: corePluginOpts.serializationAdapters,
+    }),
+    createCaptureClientBuildPlugin({
+      capturedClientBuild,
+    }),
+  ]
+}
+
+function createViteRscForwarder(strategy: ViteRscForwardSsrResolverStrategy) {
+  return `export async function getServerFnById(id, access) {
+  const m = await import.meta.viteRsc.loadModule(${JSON.stringify(strategy.sourceEnvironmentName)}, ${JSON.stringify(strategy.sourceEntry)})
+  return m[${JSON.stringify(strategy.exportName)}](id, access)
+}`
+}

package/src/vite/plugins.ts

@@ -0,0 +1,81 @@
+import { START_ENVIRONMENT_NAMES } from '../constants'
+import { normalizeViteClientBuild } from './start-manifest-plugin/normalized-client-build'
+import type {
+  GetConfigFn,
+  NormalizedClientBuild,
+  ResolvedStartConfig,
+} from '../types'
+import type { StartEnvironmentName } from '../constants'
+import type { PluginOption, ViteBuilder } from 'vite'
+
+export function createPostBuildPlugin(opts: {
+  getConfig: GetConfigFn
+  postServerBuild: (opts: {
+    startConfig: ReturnType<GetConfigFn>['startConfig']
+    builder: ViteBuilder
+  }) => Promise<void>
+}): PluginOption {
+  return {
+    name: 'tanstack-start-core:post-build',
+    enforce: 'post',
+    buildApp: {
+      order: 'post',
+      async handler(builder) {
+        const { startConfig } = opts.getConfig()
+        await opts.postServerBuild({ builder, startConfig })
+      },
+    },
+  }
+}
+
+export function createDevBaseRewritePlugin(opts: {
+  shouldRewriteDevBase: () => boolean
+  resolvedStartConfig: ResolvedStartConfig
+}): PluginOption {
+  return {
+    name: 'tanstack-start-core:dev-base-rewrite',
+    configureServer(server) {
+      if (!opts.shouldRewriteDevBase()) {
+        return
+      }
+
+      const basePrefix = opts.resolvedStartConfig.basePaths.publicBase.replace(
+        /\/$/,
+        '',
+      )
+
+      server.middlewares.use((req, _res, next) => {
+        if (req.url && !req.url.startsWith(basePrefix)) {
+          req.url = basePrefix + req.url
+        }
+
+        next()
+      })
+    },
+  }
+}
+
+export function createCaptureClientBuildPlugin(opts: {
+  capturedClientBuild: Partial<
+    Record<StartEnvironmentName, NormalizedClientBuild>
+  >
+}): PluginOption {
+  return {
+    name: 'tanstack-start:core:capture-bundle',
+    applyToEnvironment(environment) {
+      return environment.name === START_ENVIRONMENT_NAMES.client
+    },
+    enforce: 'post',
+    generateBundle(_options, bundle) {
+      const environment = this.environment.name as StartEnvironmentName
+
+      if (environment !== START_ENVIRONMENT_NAMES.client) {
+        throw new Error(
+          `Unexpected environment for client build capture: ${environment}`,
+        )
+      }
+
+      opts.capturedClientBuild[environment] = normalizeViteClientBuild(bundle)
+    },
+  }
+}

package/src/{post-server-build.ts → vite/post-server-build.ts}

@@ -1,8 +1,8 @@
 import { HEADERS } from '@tanstack/start-server-core'
-import { buildSitemap } from './build-sitemap'
-import { VITE_ENVIRONMENT_NAMES } from './constants'
+import { buildSitemap } from '../build-sitemap'
 import { prerender } from './prerender'
-import type { TanStackStartOutputConfig } from './schema'
+import { getClientOutputDirectory } from './output-directory'
+import type { TanStackStartOutputConfig } from '../schema'
 import type { ViteBuilder } from 'vite'
 
 export async function postServerBuild({
@@ -65,9 +65,7 @@ export async function postServerBuild({
   if (startConfig.sitemap?.enabled) {
     buildSitemap({
       startConfig,
-      publicDir:
-        builder.environments[VITE_ENVIRONMENT_NAMES.client]?.config.build
-          .outDir ?? builder.config.build.outDir,
+      publicDir: getClientOutputDirectory(builder.config),
     })
   }
 }