Tanstack Query Integration For React

This guide shows how to integrate oRPC with Tanstack Query for React. For an introduction, please review the Basic Guide first.

Installation

npm

npm install @orpc/react-query@latest @tanstack/react-query@latest

yarn

yarn add @orpc/react-query@latest @tanstack/react-query@latest

pnpm

pnpm add @orpc/react-query@latest @tanstack/react-query@latest

bun

bun add @orpc/react-query@latest @tanstack/react-query@latest

deno

deno install npm:@orpc/react-query@latest npm:@tanstack/react-query@latest

Setup

Before you begin, ensure you have already configured a server-side client or a client-side client.

import { createORPCReactQueryUtils } from '@orpc/react-query'

export const orpc = createORPCReactQueryUtils(client)

orpc.planet.find.
queryOptions({ input: { id: 123 } })

//

Avoiding Query/Mutation Key Conflicts

Prevent key conflicts by passing a unique base key when creating your utils:

const userORPC = createORPCReactQueryUtils(userClient, {
  path: ['user']
})
const postORPC = createORPCReactQueryUtils(postClient, {
  path: ['post']
})

Using React Context

Integrate oRPC React Query utils into your React app with Context:

1. Create the Context:

   import { createContext, useContext } from 'react'
   import { RouterUtils } from '@orpc/react-query'
   import { RouterClient } from '@orpc/server'
   
   type ORPCReactUtils = RouterUtils<RouterClient<typeof router>>
   
   export const ORPCContext = createContext<ORPCReactUtils | undefined>(undefined)
   
   export function useORPC(): ORPCReactUtils {
     const orpc = useContext(ORPCContext)
     if (!orpc) {
       throw new Error('ORPCContext is not set up properly')
     }
     return orpc
   }

2. Provide the Context in Your App:

   export function App() {
     const [client] = useState<RouterClient<typeof router>>(() => createORPCClient(link))
     const [orpc] = useState(() => createORPCReactQueryUtils(client))
   
     return (
       <ORPCContext.Provider value={orpc}>
         <YourApp />
       </ORPCContext.Provider>
     )
   }

3. Use the Utils in Components:

   const orpc = useORPC()
   
   const query = useQuery(orpc.planet.find.queryOptions({ input: { id: 123 } }))

skipToken for Disabling Queries

You can still use skipToken by conditionally overriding the queryFn property:

import { skipToken, useQuery } from '@tanstack/react-query'

const options = orpc.planet.find.queryOptions({
  input: { id: 123 },
})

const query = useQuery({
  ...options,
  queryFn: condition ? skipToken : options.queryFn,
})