Postmortem: TanStack Start Virtual Module Issue

Issue Reference

Summary

Importing directly from @tanstack/start-server-core causes Vite pre-bundling errors because the package uses virtual modules (#tanstack-router-entry) that require special Vite configuration.

Recurrence History

This issue has resurfaced multiple times, caused by PRs attempting to support both Solid and React versions of TanStack Start:

PR #6045
PR #6235
PR #7340 (v1.4.12 -> v1.4.13)

The initial fix in v1.4.14 using @tanstack/react-start-server and @tanstack/solid-start-server did not resolve the issue.

Root Cause

@tanstack/start-server-core is an internal TanStack package that has its own Vite configuration with external dependencies like #tanstack-router-entry. When better-auth tanstack-start integration imported directly from this package:

// BAD - Don't do this
import { setCookie } from "@tanstack/start-server-core";

Vite tried to pre-bundle @tanstack/start-server-core and encountered the virtual modules, causing the error:

Could not resolve "#tanstack-router-entry"

Solution

Import from the framework-specific server subpath instead, which properly re-export everything from @tanstack/start-server-core:

For React: Use @tanstack/react-start/server
For Solid.js: Use @tanstack/solid-start/server

// GOOD - For React
import { setCookie } from "@tanstack/react-start/server";

// GOOD - For Solid.js
import { setCookie } from "@tanstack/solid-start/server";

Note: The separate packages @tanstack/react-start-server and @tanstack/solid-start-server did NOT fix the issue. You must use the /server subpath from the main packages.

User Workaround

If users encounter this issue before an official fix is released, they can add the following to their vite.config.ts:

optimizeDeps: {
  exclude: ['@tanstack/start-server-core'],
},

Lesson Learned

When integrating with TanStack Start:

Never import directly from @tanstack/start-server-core - this is an internal package with virtual modules
Use framework-specific subpaths - @tanstack/react-start/server for React, @tanstack/solid-start/server for Solid.js
Do not use separate -server packages - @tanstack/react-start-server does NOT fix the issue
These packages re-export the same APIs - so setCookie, getCookie, etc. are available from both

Files Changed in Fix

packages/better-auth/src/integrations/tanstack-start.ts - Changed import to @tanstack/react-start/server
packages/better-auth/src/integrations/tanstack-start-solid.ts - Changed import to @tanstack/solid-start/server
packages/better-auth/package.json - Updated peer dependencies from @tanstack/*-start-server to @tanstack/*-start

3.2 KiB Raw Blame History