Improve start error message when importing server code on the client

[lino-levan]

Which project does this relate to?

Start

Describe the bug

When someone imports server code on the client in the current iteration of tanstack start, vite gives a very hard-to-debug error which doesn't expose what file is generating that error. This is a pretty awful issue to debug, especially for projects moving to the RC.

Split off of #5196 (comment), which you should read for more context.

Example error message:

../node_modules/@tanstack/start-server-core/dist/esm/loadVirtualModule.js:5:26:
  5 │       return await import("tanstack-start-manifest:v");
    ╵                           ~~~~~~~~~~~~~~~~~~~~~~~~~~~

Your Example Website or App

#5196 (comment)

Steps to Reproduce the Bug or Issue

import { getRequest } from "@tanstack/react-start/server";

(or similar) on a client-only file

Expected behavior

As a user, I am alright with this erroring, but the error should be actionable instead of blowing up without further guidance. Specifically, I'd really love for the error to point to the offending files.

Screenshots or Videos

No response

Platform

• Router / Start Version: 1.131.7
• OS: macOS
• Browser: All
• Bundler: Vite
• Bundler Version: 7.1.7

Additional context

No response

[karl-run]

Have you found any approach to debugging this?

[lino-levan]

Decided to punt the upgrade internally until we have more time but what has worked for a couple of them was delete everything, introduce files part by part, one by one to locate what is causing the issues.

[zemccartney]

I just ran into this issue, or at least an issue that presents in the same way (hard-to-debug error, opaque references to virtual modules). Granted, first time using tanstack start and was moving fast, likely have done something silly, but I'm at a loss for how to deal with this.

Repo with my setup, along with steps to reproduce in the README: https://github.com/zemccartney/tanstack-start-crash-repro

Notably, I can make the error temporarily go away by deleting src files, then restarting the dev server. And the app appears to build just fine. I would have thought clearing out node_modules and reinstalling would have affected how this bug presents, but as far as I can tell, no effect.

Platform

• Router / Start Version: 1.133.36
• OS: macOS
• Browser: All
• Bundler: Vite
• Bundler Version: 7.1.12
• Node version: v22.14.0

[rburgst]

I am having the same issues, the only remedy i found is going back to the last good commit, then apply the next one and remove lines one after the other until it starts working. It ALWAYS happens when you have server functions that import other server only code.
I mean I dont want to wrap EVERY single utility server method into a server function! This is not going to fly. Also I had some issues integration testing or unit testing server functions (throwing weird error messages around, ended up exporting a stripped down method that didnt include any of the server function stuff.
So in general I feel still very skeptical even though the hello world experience is truly quite good. It only starts to suck if you want to build a real app (you know with test etc) that things tend to go awry.
I would really love to like tanstack-start (because I do love tanstack-router), but its making it SUPER difficult right now as there are many paper cuts like this one.
I feel that everyone trying to build someting moderately complex with db, tests, etc), will pull his hair out with tanstack-start right now.
Can I please get a "use server" on the top of files where I can tell the bundler to PLEASE PLEASE PLEASE dont even think bundling this in the client?

[schiller-manuel]

no there wont be a "use server"
but something similar maybe.

[rburgst]

I dont mind how its called, what I would really like is some way to have one set of files that are server only (maybe have them in a separate folder, have some file naming convention, have some ignored first line like "use server", I dont care).

However it MUST be trivial to solve those issues. Because right now if you are trying to build a drizzle powered server which uses the same schema-derived data structures to use in your client forms (tanstack-forms, I am looking at you), then this is like pulling good teeth. It sucks really bad.
I had to resort to using dynamic imports just to get the bundler to stop following server only imports.
It shouldnt be so hard.
I am watching tons of youtube videos where people are chanting over how nice tanstack start is, when you look at their implementations, they use in memory server side stuff where most likely all their server code IS being bundled on the client, but its so trivial and doesnt use any library that it doesnt matter.
For a good framework that people will continue to use it should be the other way round. The more you learn about it, the more pleasant it should become. Unfortunately right now its the other way round. As soon as you are trying to do something interesting it becomes unreasonably hard where neither stackoverflow, the github issue tracker or any LLM can really help you.
So @schiller-manuel as soon as you have something that would fit that bill, please let me know (I hope by then I will still be on tanstack-start).

[schiller-manuel]

can you share a complete project where this occured?
also what would you expect if the client env imports something directly or transitively from such a marked file?

[rburgst]

hi, will try to whip something together in the next few days, here is some example for a rough idea

import {taskRepository} from './server/task-repository'

export const getListTasks = createServerFn({ method: 'GET' })
  .middleware([authWithLocaleMiddleware])
  .handler(async (ctx) => {
    const tasks = await taskRepository.getTasks()
    return tasks
  })

basically this does not work as it would then try to bundle task-repository (and drizzle etc) into the client and there is no obvious way to make this work, regardless of whether the export is a function or anything else.

I would hope that marked files (lets just call it 'use server' for now as I dont know what else to call it) would then be ignored by the bundler and will not make it into the client bundle. That way will allow you to write "normal" server code and then brigdge the gap via createServerFunction in case you want to expose this method to the client.

Just found this doc

https://tanstack.com/start/latest/docs/framework/react/guide/execution-model#server-only-execution

It nicely hides where db is actually coming from. I pretty much guarantee that this wont work either due to the same problem

import { createServerFn, createServerOnlyFn } from '@tanstack/react-start'

// RPC: Server execution, callable from client
const updateUser = createServerFn({ method: 'POST' })
  .inputValidator((data: UserData) => data)
  .handler(async ({ data }) => {
    // Only runs on server, but client can call it
    return await db.users.update(data)
  })

// Utility: Server-only, client crashes if called
const getEnvVar = createServerOnlyFn(() => process.env.DATABASE_URL)

So basically, I urge you to try and get this to work without wrapping everything in createServerOnlyFunction (and still then your import of the drizzle db object will break your neck).

Maybe I am holding it wrong and there is a super simple solution for such problems. If thats the case - great - but please update the docs.

[abenhamdine]

I just discovered this thread after having decided to migrate my Next.js app to TanStack, arggh
I'm puzzled, how is it possible to build even a simple app if we cannot import server code from a server function ?

[alessandrojcm]

Same here, been trying to migrate a React Router 7 + Hono custom setup to TansStack and hitting the same error as the OP. I have multiple server-only utilities to interface with my DB, Redis, etc. I would have expected for these to be importable within a file that defines a server function like @rburgst says however it seems I am hitting the same limitation. I understand Start is RC still but I don't seem to be able to find any examples where a proper full-stack app with drizzle/prisma/etc is used with a server function, is there such an example? I know I could create API routes but that kinda defeats the purpose of migrating on the first place.

[rburgst]

@alessandrojcm I have to confess that the create-tanstack-app generator creates a working version where this problem is not happening, I am still in the process of trying to merge my app (where I have the problem) and the working generated app to illustrate the problem better.
However, it does seem that at least for simple apps it is in fact working. As stated earlier the more involved your app becomes the more likely you are to run into this problem.
I was actually considering converting my app to hono + TSR :)

[alessandrojcm]

@rburgst yeah, that is fair. I know that the generator apps and simple apps work, the issue is that my app is already pretty involved and such these errors are really hard to track down. I've seen the TSR + Hono approach. I just think that using a server framework inside a full-stack framework is a bit convoluted.

[rburgst]

@schiller-manuel I am having problems replicating a simplified example. I do have my (complex) project where i can reproduce the problem, do you have any ideas how I can debug the problem to find out what exactly makes it break. I tried running the build with DEBUG=* pnpm build but that is generating so much log that its quite useless

This is my current error where its trying to bundle pg into the client.

✗ Build failed in 7.35s
error during build:
[vite]: Rollup failed to resolve import "pg" from "/Users/rainer/git/private/project/src/lib/database.ts".
This is most likely unintended because it can break your application at runtime.
If you do want to externalize this module explicitly add it to
`build.rollupOptions.external`

[rburgst]

I guess this is related #5892