How to pass custom request headers per-call with @orpc/client and @orpc/tanstack-query

[dugajean]

I'm using @orpc/client with @orpc/tanstack-query and need to pass custom headers on a per-request basis (specifically for Turnstile captcha verification via x-captcha-response header).

Current setup:

import { createORPCClient } from "@orpc/client";
import { RPCLink } from "@orpc/client/fetch";
import { createTanstackQueryUtils } from "@orpc/tanstack-query";

const client = createORPCClient<RouterContract>(
  new RPCLink({
    url: "/rpc",
    fetch: (url, init) => fetch(url, { ...init, credentials: "include" }),
  }),
);

export const orpc = createTanstackQueryUtils(client);

What I'm trying to do:

// With tanstack-query integration
const mutation = useMutation(
  orpc.myProcedure.mutationOptions({
    // How do I pass custom headers here?
  })
);

mutation.mutate(data, {
  // Or here?
});

// Or directly with client
await client.myProcedure(data, {
  headers: { "x-captcha-response": token }, // Does this work?
});

Current workaround:

I'm bypassing ORPC entirely and using ky/fetch directly for endpoints that need custom headers:

await ky.post("/rpc/myProcedure", {
  json: data,
  headers: { "x-captcha-response": token },
});

This works but loses type safety and the nice DX of the ORPC client.

Questions:

Is there a way to pass per-request headers with the client directly?
Is there a way to pass headers through mutationOptions or the mutate call?
If not currently supported, is this on the roadmap?

Thanks!

[dosubot[bot]]

There isn't built-in support for passing custom headers per-request directly via the second argument to client calls (like client.myProcedure(data, { headers })) or through mutationOptions/mutate in the TanStack Query integration. However, you can achieve per-request headers by leveraging the context mechanism and customizing your RPCLink's headers function.

Here's how you can do it:

1. When creating your RPCLink, set the headers option to a function that reads from the context:

const client = createORPCClient<RouterContract>(
  new RPCLink({
    url: "/rpc",
    fetch: (url, init) => fetch(url, { ...init, credentials: "include" }),
    headers: (options) => options.context?.headers ?? {},
  }),
);

2. When making a call, pass your custom headers inside the context property:

await client.myProcedure(data, {
  context: { headers: { "x-captcha-response": token } }
});

3. For TanStack Query integration, mutationOptions and mutate do not accept headers directly, but you can pass context the same way:

const mutation = useMutation(
  orpc.myProcedure.mutationOptions({
    context: { headers: { "x-captcha-response": token } }
  })
);

// Or when calling mutate:
mutation.mutate(data, {
  context: { headers: { "x-captcha-response": token } }
});

This approach keeps type safety and lets you inject headers per call. The key is that your RPCLink's headers function must pull from options.context. This pattern is the recommended workaround for now, as direct per-request header support in mutationOptions/mutate isn't currently available or planned in the immediate roadmap (reference, reference).

Let me know if you want a more detailed example or have questions about advanced header handling!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[unnoq]

Can this solve your problem? https://orpc.dev/docs/client/rpc-link#using-client-context