Importing server functions from router.tsx causes errors

[laptou]

I defined some server functions like this:

// src/lib/auth.functions.ts

import {
	createClientOnlyFn,
	createIsomorphicFn,
	createServerFn,
} from "@tanstack/solid-start";
import { authClient } from "./auth";
import {
	ensureSession as ensureSessionServer,
	getSession as getSessionServer,
	listActiveSubscriptions as listActiveSubscriptionsServer,
} from "./auth.server";

const getSessionClient = createClientOnlyFn(async () => {
	const result = await authClient.getSession();
	if (result.error) throw result.error;

	return result.data;
});

/// returns the current session or null if not authenticated.
export const getSession = createIsomorphicFn()
	.server(() => getSessionServer())
	.client(() => getSessionClient());

/// like getSession but throws a 401 response if unauthenticated.
// export const ensureSession = createServerFn({ method: "GET" }).handler(
// 	() => ensureSessionServer(),
// );

/// returns active Better Auth subscriptions for the current user.
export const listActiveSubscriptions = createServerFn({
	method: "GET",
	// ERROR IS THROWN FROM THIS LINE
}).handler(() => listActiveSubscriptionsServer());

export type { ActiveSubscriptionSummary } from "./auth.server";

Then, I try to import from src/router.tsx so that I can inject the session as router context:

// src/router.tsx
import {
	type DehydratedState,
	dehydrate,
	hydrate,
	QueryClient,
	QueryClientProvider,
} from "@tanstack/solid-query";
import { createRouter } from "@tanstack/solid-router";
// COMMENTING OUT THIS IMPORT REMOVES THE ERROR
import { getSession } from "./lib/auth.functions";
import { installFatalListeners } from "./lib/errors";
import type { RouterContext } from "./routes/__root";
import { routeTree } from "./routeTree.gen";
import * as Sentry from "@sentry/node";
import { SessionData } from "./lib/auth";

type JsonValue =
	| null
	| boolean
	| number
	| string
	| JsonValue[]
	| { [key: string]: JsonValue };

type DehydratedRouterState = {
	queryClientState?: JsonValue;
};

async function createAppRouter() {
	const queryClient = new QueryClient();
  let authSession: SessionData | null = null;

  try {
    authSession = await getSession();
  } catch(e) {
    console.error('failed to get auth session', e);
    Sentry.captureException(e);
  }

	return createRouter({
		routeTree,
		context: {
			authSession: null,
			queryClient,
		} satisfies RouterContext,
		defaultViewTransition: true,
		scrollRestoration: true,
		dehydrate: (): DehydratedRouterState => ({
			queryClientState: dehydrate(queryClient) as unknown as JsonValue,
		}),
		hydrate: (dehydrated: DehydratedRouterState) => {
			if (dehydrated.queryClientState) {
				hydrate(
					queryClient,
					dehydrated.queryClientState as unknown as DehydratedState,
				);
			}
		},

		Wrap: (props) => (
			<QueryClientProvider client={queryClient}>
				{props.children}
			</QueryClientProvider>
		),
	});
}

declare module "@tanstack/solid-router" {
	interface Register {
		router: Awaited<ReturnType<typeof createAppRouter>>;
	}
}

export async function getRouter() {
	const router = await createAppRouter();

	// initialization code omitted for brevity, Sentry setup, etc

	return router;
}

And I get an error in my browser console:

Uncaught (in promise) ReferenceError: process is not defined
    at createClientRpc (createClientRpc.ts:7:15)
    at auth.functions.ts:33:11

Is this a bug, or am I misusing the framework by trying to import server functions here? I'm inclined to think it's a bug because the error is being thrown from a function that I'm not actually calling (the stack trace points to the call to .handler() in listActiveSubscriptions).

[schiller-manuel]

can you please share a complete minimal reproducer project as a git repo?

also, you should use the query integration https://tanstack.com/router/latest/docs/integrations/query

[laptou]

thanks for the tip. here's a minimal reproduction: laptou/tss-server-fn-bug-repro@f879474

it seems out that if you import routeTree.gen.ts after any file that defines a server function then you get errors during dev mode. it doesn't seem to break prod builds. in case it is helpful in fixing this issue, here is what an LLM said while i was debugging this:

This is genuinely a bug in @tanstack/start-client-core
The library is reading process.env.TSS_SERVER_FN_BASE at module init time, in this line:

// createClientRpc.js
// Lines 5-7
function createClientRpc(functionId) {
	const url = process.env.TSS_SERVER_FN_BASE + functionId;
	const serverFnMeta = { id: functionId };

Because that file is optimizeDeps.excluded, the literal process.env.TSS_SERVER_FN_BASE never gets statically replaced in dev. It only "works" if a runtime polyfill is in place by the time createClientRpc("…") is invoked at the top level of a generated server-fn module — which depends on import ordering elsewhere in the user's code. The right fix in the library would be to either:

Compute url lazily inside clientFn (so it's evaluated at call time, well after all dev-mode scripts have run), or
Drop @tanstack/start-client-core from optimizeDeps.exclude so esbuild static replacement runs, or
Use import.meta.env.TSS_SERVER_FN_BASE instead (Vite inlines that explicitly via hasEnv regardless of optimize-deps state).

it seems like the code in vite's client entry which defines process.env is only executed under certain conditions (which are triggered by importing routeTree.gen.ts), so any code that access process.env before these conditions are triggered will crash

[schiller-manuel]

/lib/test.functions does not exist in your reproducer

[MILLERMARRU]

I hit this exact class of error with Start and traced it to createClientRpc. The generated client stub for a server function looks like this in start-client-core:

export function createClientRpc(functionId: string) {
  const url = process.env.TSS_SERVER_FN_BASE + functionId
  // ...
}

That process.env.TSS_SERVER_FN_BASE is meant to be statically replaced with a literal string by the Start Vite plugin at build/transform time, the same way process.env.NODE_ENV gets replaced by bundlers generally. It only survives into the client bundle unresolved if the file containing your createServerFn(...) call never actually goes through Start's client/server split transform for that module.

That transform is scoped to the route module graph, route files and whatever gets pulled in through the compiler's known entry points, not to router.tsx itself, since router.tsx is the router factory and ends up included more directly in both the client and server builds rather than going through the same per-route split. Importing your server-fn module straight into router.tsx at module scope is exactly the case that slips past that split, so the client bundle ends up with the raw createClientRpc wrapper, unreplaced process.env reference and all, hence process is not defined in the browser.

This matches what the import-protection feature is meant to catch (see the discussion right next to yours, #7390), so I'd call it a real gap rather than a misuse on your part, but the practical fix today is to not import server-function modules directly into router.tsx. Fetch the session where the router can actually reach it safely, in beforeLoad on your root route instead:

// routes/__root.tsx
export const Route = createRootRouteWithContext<RouterContext>()({
  beforeLoad: async () => {
    const authSession = await getSession()
    return { authSession }
  },
})

and drop the eager context: { authSession: null, ... } population out of createAppRouter, letting beforeLoad populate it instead. schiller-manuel's suggestion of the query integration is worth doing too if you specifically want to prefetch/dehydrate data through TanStack Query, but for the router-context-injection pattern itself, moving the server-fn import off router.tsx is what actually removes the error you're seeing.