`vite.preview()` called during static prerendering doesn't forward `configLoader`, causing preview server to crash (EASY FIX)

[sebastienbarre]

Which project does this relate to?

Start

Describe the bug

Hopefully this explanation is detailed enough, but the fix is only one line.

The bug

When using tanstackStart({ prerender: { enabled: true } }) with a monorepo where --configLoader native is required to launch Vite, the prerender server will crash.

Root cause

After the client and SSR builds complete, @tanstack/start-plugin-core/src/vite/prerender.ts spins up a Vite preview server to handle prerender requests (here):

// packages/start-plugin-core/src/vite/prerender.ts
async function startPreviewServer(viteConfig: ResolvedConfig): Promise<PreviewServer> {
  const vite = await import('vite')
  return await vite.preview({
    configFile: viteConfig.configFile,
    preview: { port: 0, open: false },
    // ← configLoader is NOT forwarded
  })
}

This calls vite.preview() without forwarding the configLoader from the original invocation. The configLoader field defaults to 'bundle' (I need native instead), which makes Vite re-parse vite.config.ts using Rolldown's internal config bundler. This causes the preview server to crash because it doesn't have the custom condition from NODE_OPTIONS="--conditions=@repo/source" that would allow it to resolve any package export that requires said custom condition.

Complete minimal reproducer

https://github.com/sebastienbarre-forks/tanstack-start-example-basic-static-crash

Steps to Reproduce the Bug

$ pnpm install
$ pnpm build

You should see:

✓ built in 263ms
failed to load config from/start-basic-static/packages/app/vite.config.ts
error during build:
Error: Failed to start the Vite preview server for prerendering
    at startPreviewServer (file:///start-basic-static/node_modules/.pnpm/@tanstack+start-plugin-core@1.171.17_@tanstack+react-router@1.170.15_react-dom@19.2.7_r_271e9cf7e315f271d5a87ddafbf33008/node_modules/@tanstack/start-plugin-core/dist/esm/vite/prerender.js:41:9)

If you follow the above link to the bundled file, you will find the throw:

async function startPreviewServer(viteConfig) {
	const vite = await import("vite");
	try {
		return await vite.preview({
			configFile: viteConfig.configFile,
			preview: {
				port: 0,
				open: false
			}
		});
	} catch (error) {
		throw new Error("Failed to start the Vite preview server for prerendering", { cause: error });
	}
}

The call to vite.preview() is just missing one line to propagate the config loader (see below).

Expected behavior

The vite.preview() call in startPreviewServer should forward configLoader (and ideally all relevant InlineConfig fields) from the resolved config of the original build. This is easy, a one line change (I tested it by hard-coding it in the shipped dist/esm/vite/prerender.js):

return await vite.preview({
  configFile: viteConfig.configFile,
  configLoader: viteConfig.inlineConfig?.configLoader,  // ← propagate
  preview: { port: 0, open: false },
})

Note: configLoader is part of Vite 8's InlineConfig type

Screenshots or Videos

N/A

Platform

• TanStack Start 1.168.25 (I believe)
• macOS
• Browser: N/A
• Bundler: Vite
• Bundler Version: 8.0.16

Additional context

Thank you!

[sebastienbarre]

Friendly tag of @edmundhung since they worked on this code (issue #5921). Hopefully this makes sense.

[edmundhung]

Does --configLoader has a corresponding config option inside vite config? If it's available only through the CLI argument, I think it's valid to do so.

[sebastienbarre]

Hell @edmundhung ; I managed to create a monorepo for you to reproduce the error. Sorry for the delay. In the process, I realized this is not a warning, this is actually a crash, the whole preview server will crash (throw) in this small monorepo. Same cause, same easy fix, but I updated the title and body of the message accordingly, this is more severe than in my monorepo.

The --configLoader has an equivalent option as far as the vite.preview API is concerned, that's the one mentioned in my fix, and the root of the issue:

configLoader: viteConfig.inlineConfig?.configLoader

The Vite config's resolve.conditions or ssr.resolve.conditions options are related, but NOT the fix (see below).

[sebastienbarre]

Update: maybe I misunderstood your question. No, there is no equivalent option inside the Vite config; if there was such an option, it would be too late to put it in the Vite config anyway; --configLoader is the option that governs what will be used to parse the Vite config, this happens before the Vite config is even set up. The crash happens because the preview server is initialized by re-reading the Vite config (the call to vite.preview calls with configFile: viteConfig.configFile), and since it is not using the same loader anymore, it throws because it doesn't have the NODE_OPTIONS the --configLoader native is using to actually parse the Vite config without erroring. Sorry if you knew all that already.

This is related to setting resolve.conditions: ['@repo/source'] in the Vite config, yes, but that part is for the bundler (and I assume, passed down to Rolldown). The part that is missing is for situations where the Vite config itself needs to resolve packages that require that custom condition. In this monorepo example, it's the import { MY_CONSTANT } from '@repo/support'; found in vite.config.ts. The @repo/support's package.json states:

    ".": {
      "@repo/source": "./src/index.ts",
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    },

Therefore the @repo/source custom condition is needed to import it "live; the goal here is to vite dev or vite build with live types, since Vite can bundle both the app and the dependencies found in @repo/support. This needs to work even if the support libraries have not been built. In my real monorepo, there are situations where consumers will need to use the transpiled code in dist/ and other situations where Vite can work with live sources; this setup is meant to accommodate both.

[sebastienbarre]

This commit introduces the NODE_OPTIONS and Node.js custom exports condition that reveal this issue.

If you are curious, this is in relation to Colin McDonnell (colinhacks)'s Live types in a TypeScript monorepo, i.e. how to setup a monorepo where types are live and you do not have to build anything, while still having the ability to build your internal packages for publishing. Custom conditions are a way to solve this. You need to set them up in your TSConfig compilerOptions.customConditions, as well as your calls to Node using --conditions (or NODE_OPTIONS in the case of vite build), and in your Vite config's resolve.conditions (phew).

[edmundhung]

--configLoader is the option that governs what will be used to parse the Vite config, this happens before the Vite config is even set up.

Ah, thanks for clarifying. That makes sense to me. But I'm not on the TanStack team, so I will defer to them on the final decision :)