Feature Request: First-Party React Query Helpers for TanStack Start Server Functions

[frixou89]

Feature Request: First-Party React Query Helpers for TanStack Start Server Functions

Summary

I'd like to propose first-party React Query helpers for TanStack Start server functions.

The main pain point is cache ergonomics. Server functions already give a good way to define server-side logic, but when using them with React Query, I still need to manually wire query keys, query functions, mutation setup, and invalidation behavior. That creates repetitive boilerplate and makes it easy for cache logic to drift over time.

What would help is a way to derive React Query helpers directly from a server function so that the function itself becomes the source of truth for both execution and cache identity.

Proposed DX

This is the kind of developer experience I would love to have:

• Assume getEntity and removeEntity are server functions
• useServerFnQuery extracts metadata and helper utils for react-query

const { queryOptions, pathKey } = useServerFnQuery(getEntity)
const { mutationOptions } = useServerFnQuery(removeEntity)

const { data } = useQuery(queryOptions)

const mutation = useMutation(
  mutationOptions({
    onSettled: () =>
      queryClient.invalidateQueries({
        queryKey: pathKey(),
      }),
  }),
)

Alternative DX Proposal: Query-Client-Level Integration

A second possible API direction is to integrate server-function helpers at the Query Client layer, so apps can configure one enhanced client and use it everywhere.

Example

// router.tsx
export const queryClient = new StartQueryClient()

// some route/component file
const { queryOptions, pathKey } = queryClient.useServerFn(getEntity)
const { mutationOptions } = queryClient.useServerFn(removeEntity)

const { data } = useQuery(queryOptions({ id: entityId }))

const mutation = useMutation(
  mutationOptions({
    onSettled: () =>
      queryClient.invalidateQueries({
        queryKey: pathKey(),
      }),
  }),
)

The key benefit here is that I don't have to manually define or repeat cache keys in multiple places. The server function drives both the request behavior and the cache behavior.

Why This Would Help

• Reduces manual query key management
• Makes invalidation more reliable
• Removes repeated queryFn and mutation boilerplate
• Encourages a more consistent integration pattern across apps
• Makes TanStack Start server functions feel like a more complete data boundary when paired with React Query

[Scholar01]

I have encountered the same problem, it's very cumbersome, and I hope to get support.

[ahmafi]

ORPC & TRPC integrations also have very good DX, in my opinion.

Very similar to what's proposed, but with a single object having reference to all APIs, in the context and style of Tanstack I don't think that's viable.

One problem with this approach might be that we need to define the queryKey inside useServerFnQuery based on something, such as server function URL. If we do that, we lose some of the benefits of queryKey, such as Partial Query Matching.
TRPC can work around this because it gathers all API routes under one or multiple object and therefore can invalidate multiple queries.

[ahmafi]

I'm not very comfortable with Typescript generics and Tanstack types, but managed to create this based on what is proposed:

import { queryOptions, type UseQueryOptions } from "@tanstack/react-query";
import { useServerFn } from "@tanstack/react-start";

// Borrowed these two types from TRPC
export type QueryType = "any" | "infinite" | "query";

export type TRPCQueryKeyWithoutPrefix = [
    path: string[],
    opts?: { input?: unknown; type?: Exclude<QueryType, "any"> },
];

type AnyFetcher = { url: string } & ((...deps: Array<any>) => Promise<any>);

export function useServerFnOptions<T extends AnyFetcher>(
    serverFn: T,
): (
    ...args: Parameters<T>
) => UseQueryOptions<
    Awaited<ReturnType<T>>,
    Error,
    Awaited<ReturnType<T>>,
    TRPCQueryKeyWithoutPrefix
> {
    const serverFnAction = useServerFn(serverFn);

    const queryOptionsBuilder = (...args: Parameters<T>) =>
        queryOptions({
            queryKey: [
                [serverFn.url],
                { input: args },
            ] as TRPCQueryKeyWithoutPrefix,
            queryFn: () => serverFnAction(...args),
        });

    return queryOptionsBuilder;
}

Usage:

const productsQueryOptions = useServerFnOptions(getDomains);
const products = useQuery(productsQueryOptions({ data: {} }));