There is an obvious appeal to a server function you can call from anywhere. The old version of the same idea was not pleasant. You wrote an endpoint, then a client helper for that endpoint, then some shared schema to keep the two sides honest, then error handling in both places, and eventually a small pile of files whose main job was to move one value from the browser to the server and another value back again.
So when a framework lets you write the server part as a normal function and call it as a normal function, it feels like the right kind of progress.
export const getUser = createServerFn().handler(async () => {
return db.user.findCurrent()
})
Somewhere else:
const user = await getUser()
This is much nicer than wiring an endpoint by hand. The function is typed. The caller is typed. Refactors have a path through the codebase instead of disappearing into a string URL. For a lot of application code, especially small reads and mutations, this is exactly the kind of boilerplate a framework should remove.
The question is not whether the API is useful. It is. The question is what gets hidden when the call becomes this smooth.
The same call is not always the same operation
await getUser() can mean slightly different things depending on where it appears. If the call happens while the application is already running on the server, it can be a direct path into server code. If it happens in the browser, it has to become a request. If it happens in a route loader, it belongs to the router's data lifecycle. If it happens after a click, it belongs to an interaction that the user is waiting on.
Those cases can all share the same TypeScript signature, but they are not the same situation. The value that comes back may have the same shape; the act of getting it does not.
That is the part of isomorphic server functions that makes me uneasy. The abstraction removes a lot of code nobody wanted to write, but it also makes the call site less descriptive. The line looks ordinary in places where the operation behind it may not be ordinary at all.
What TanStack makes pleasant
TanStack Start leans into this trade quite naturally. A server function is explicit when it is defined, and then the exported value is designed to be called from the places where application code tends to need it: loaders, components, hooks, event handlers, other server functions. That fits the rest of TanStack's style. The router is central, the data flow is typed, and the application is assembled out of explicit functions rather than a large menu of special filenames. If that is already the way you want to build, the server function API feels consistent.
There is nothing dishonest about the definition site. createServerFn() tells you that the handler is server code. It can touch a database. It can read secrets. It can do work the browser cannot do. The ambiguity appears later, when the call has been made deliberately ordinary.
That ordinariness is useful while you are writing the code. You know where you are. You know whether the call is inside a loader or inside a button handler. You know what the framework is going to do. The problem shows up later, when the code is read without all of that context already loaded into someone's head.
A small refactor changes the role
Imagine a settings page that starts like this:
export const Route = createFileRoute("/settings")({
loader: () => getUser(),
component: SettingsPage,
})
Later, someone adds a refresh button inside the page:
async function refresh() {
const user = await getUser()
setUser(user)
}
Both calls are reasonable. Both may be exactly what the application wants. But they are not playing the same role anymore. The first call belongs to navigation. The second call belongs to an interaction after the page is already on screen. It has a different timing, a different failure shape, probably a different loading state, and possibly a different relationship to invalidation.
Nothing about getUser() is wrong here. The issue is that the call is too polite to mention that its role changed. The code moved from one part of the application to another, and the most important difference is now carried by the surrounding framework context rather than by the expression itself.
Types do not carry place
Types do not really solve this. They solve an important part of it, but not this part. Promise<User> tells me what value I will eventually get. It does not tell me why I am waiting. It does not tell me whether the delay is a database query in the same process or a request from the browser to the server. It does not tell me whether cookies are involved, whether middleware runs, whether a rate limit can trip, or whether the user is now staring at a disabled button.
All of those things can live behind the same return type.
What RSC keeps visible
This is where React Server Components come from a different direction. RSC does not try to make server code and client code feel like the same kind of code. It lets them participate in the same React tree, but it keeps their environments distinct. Server Components run on the server. Client Components run in the browser. Server Functions are server code that can be referenced across the boundary.
The same settings page has a different shape in that model:
export default async function SettingsPage() {
const user = await getUser()
return <SettingsForm user={user} refreshUser={refreshUser} />
}
async function getUser() {
return db.user.findCurrent()
}
async function refreshUser() {
"use server"
return db.user.findCurrent()
}
"use client"
export function SettingsForm({ user, refreshUser }) {
const [currentUser, setCurrentUser] = useState(user)
async function refresh() {
setCurrentUser(await refreshUser())
}
// ...
}
There is more ceremony here. The client piece has to be named. The server function has to be passed across the boundary. Depending on the framework, this may also mean another file. But the roles are visible in the shape of the code: the initial read belongs to the Server Component, and the later refresh is a client interaction calling a Server Function.
The split does not necessarily have to be a file split. With function-level boundaries, the same idea could live much closer to the place where it is used:
export default async function SettingsPage() { const user = await getUser() function SettingsForm() { "use client" const [currentUser, setCurrentUser] = useState(user) async function refreshUser() { "use server" return db.user.findCurrent() } async function refresh() { setCurrentUser(await refreshUser()) } // ... } return <SettingsForm /> }That is the argument in The "use client" Tax: the boundary should stay visible, but it should be allowed to live closer to the code it describes.
The current ergonomics of that model are not perfect. Next's file-level "use client" boundary creates real friction, and small interactive pieces often end up in files that exist mostly because the bundler needs a module boundary. That is not a minor annoyance; it changes how code is organized. But the underlying idea is still important: a piece of code should communicate where it belongs.
When something is server code, the reader should be able to expect server capabilities. When something is client code, the reader should be able to expect browser capabilities. When a value or reference crosses from one side to the other, the model should have a visible place for that crossing. Not because visible boundaries are beautiful in themselves, but because hidden boundaries tend to come back later as surprises about latency, failure, serialization, or state.
This is the difference I care about between the two approaches. With an isomorphic server function, the definition says "server", but the call site tries to feel universal. With RSC, the model keeps insisting that server and client are different places, even when they are composed together.
The boundary should be cheap, not invisible
I do not think the answer is to give up the convenience of server functions. Hand-written endpoints are not some lost paradise. A framework should make it cheap to invoke server code from the client, and TanStack's version of that idea is useful. The part I would be careful with is the framing. There is a difference between "this is server code with a convenient client invocation mechanism" and "this is just a function you can call from anywhere."
The first framing keeps the boundary in the reader's mind. The second makes the boundary feel incidental until some operational detail forces it back into view.
That is not just a matter of taste. It becomes a real maintenance problem.
It shows up in code review, when a harmless-looking call has moved from a loader into an event handler and the diff does not make the change feel as large as it is. It shows up in debugging, when a line that reads like a function call fails like a network interaction. It shows up in refactors, when moving code across an invisible boundary changes timing, failure, and user-visible behavior without changing the expression that caused it.
That is why I find the RSC direction healthier, even with its current rough edges. The goal should not be to make every server call dramatic. It should not be to reintroduce ceremony for its own sake. It should be to make the boundary cheap enough that we can keep it visible without resenting it.
A function does not need to shout where it runs. But if understanding the function requires knowing whether it is local code, server code, or a request in disguise, then that fact should not live only in the reader's memory of the framework. Once the boundary is invisible at the call site, every reader has to rediscover it later.
Top comments (0)