Loaders, useServerFn and queryOptions

[isc30]

Hi, I'm trying to figure out how to use queryOptions together with useServerFn.

I'm trying to follow the pattern of creating predefined queries and use them from react:

export const resourceParticipationsQuery = ({
  resourceId,
}: {
  resourceId: string
}) => {
  const queryFn = useServerFn(getResourceParticipationsServerFn)
  return queryOptions({
    queryKey: ['resourceParticipations', resourceId],
    queryFn: async () => await queryFn({ data: { resourceId } }),
  })
}

This works on the client, but crashes when used on the loader.

loader: () => {
  void queryClient.prefetchQuery(
      resourceParticipationsQuery({ resourceId })
    )
}

I have tried creating a helper using createIsomorphicFn to handle both cases but it doesn't seem like it works well either.
Is there a "proper" way of doing this without code duplication?

The only solution that works reliably seems to duplicate the code:

// to be used from react
export const useResourceParticipationsQuery = ({
  resourceId,
}: {
  resourceId: string
}) => {
  const queryFn = useServerFn(getResourceParticipationsFn)
  return queryOptions({
    queryKey: ['resourceParticipations', resourceId],
    queryFn: async () => await queryFn({ data: { resourceId } }),
  })
}

// to be used from loader
export const getResourceParticipationsQuery = ({
  resourceId,
}: {
  resourceId: string
}) => {
  return queryOptions({
    queryKey: ['resourceParticipations', resourceId],
    queryFn: async () =>
      await getResourceParticipationsFn({ data: { resourceId } }),
  })
}

[travisbreaks]

The issue is that useServerFn is a React hook — it can only be called inside React components, not inside queryOptions (which runs in loaders and other non-React contexts).

The fix: call the server function directly in queryOptions

import { createServerFn } from '@tanstack/start'
import { queryOptions } from '@tanstack/react-query'

// Define the server function once
const getResourceParticipations = createServerFn({ method: 'GET' })
  .validator((data: { resourceId: string }) => data)
  .handler(async ({ data }) => {
    // fetch...
  })

// Works everywhere — loader, component, wherever
export const resourceParticipationsQuery = ({ resourceId }: { resourceId: string }) =>
  queryOptions({
    queryKey: ['resourceParticipations', resourceId],
    queryFn: () => getResourceParticipations({ data: { resourceId } }),
  })

Why this works

• In a server context (loader): TanStack Start executes the handler directly — no network round-trip
• In a client context: it makes the appropriate RPC call automatically

This is the isomorphic pattern TanStack Start is designed around. The server function itself is already isomorphic — you don't need useServerFn to make it work on both sides.

When to use useServerFn

useServerFn is specifically for React components where you need hook-style state integration (pending state, error boundaries, etc.) — think of it like useMutation for server functions. For plain data fetching in queryOptions, call the function directly every time.