TanStack Start Adapter

Use oRPC inside a TanStack Start project by mounting a handler in a server route.

TanStack Start is a full-stack React framework built on Vite and the Fetch API, so oRPC integrates through the Fetch API Adapter.

Server

You set up an oRPC server inside TanStack Start using its Server Routes.

import { onError } from '@orpc/server'
import { RPCHandler } from '@orpc/server/fetch'
import { createFileRoute } from '@tanstack/react-router'

const handler = new RPCHandler(router, {
  interceptors: [
    onError((error) => {
      console.error(error)
    }),
  ],
})

export const Route = createFileRoute('/api/rpc/$')({
  server: {
    handlers: {
      ANY: async ({ request }) => {
        const { response } = await handler.handle(request, {
          prefix: '/api/rpc',
          context: {} // Provide initial context if needed
        })

        return response ?? new Response('Not found', { status: 404 })
      },
    },
  },
})

Client

Use createIsomorphicFn to configure the link with environment-specific settings for both browser and SSR environments:

import { RPCLink } from '@orpc/client/fetch'
import { createIsomorphicFn } from '@tanstack/react-start'
import { getRequest, getRequestHeaders } from '@tanstack/react-start/server'

const getClientLink = createIsomorphicFn()
  .client(() => new RPCLink({
    url: '/api/rpc',
  }))
  .server(() => new RPCLink({
    url: '/api/rpc',
    origin: () => new URL(getRequest().url).origin, // resolve from the incoming request
    headers: () => getRequestHeaders(),
  }))

Optimize SSR

To reduce HTTP requests and improve latency during SSR, you can use a server-side client during SSR. Below is a quick setup, see Optimizing SSR for more details.

import type { RouterClient } from '@orpc/server'
import { createORPCClient } from '@orpc/client'
import { RPCLink } from '@orpc/client/fetch'
import { createRouterClient } from '@orpc/server'
import { createIsomorphicFn } from '@tanstack/react-start'
import { getRequestHeaders } from '@tanstack/react-start/server'

const getORPCClient = createIsomorphicFn()
  .server(() => createRouterClient(router, {
    /**
     * Provide initial context if needed.
     *
     * Because this client instance is shared across all requests,
     * only include context that's safe to reuse globally.
     * For per-request context, use middleware context or pass a function as the initial context.
     */
    context: async () => ({
      headers: getRequestHeaders(), // provide headers if initial context required
    }),
  }))
  .client((): RouterClient<typeof router> => {
    const link = new RPCLink({
      url: '/api/rpc',
    })

    return createORPCClient(link)
  })

export const client: RouterClient<typeof router> = getORPCClient()