RPCLink

RPCLink enables communication with an RPCHandler on your server using HTTP/Fetch.

Overview

Before using RPCLink, ensure your server is running an RPCHandler.

import { RPCLink } from '@orpc/client/fetch'

const link = new RPCLink({
  url: 'http://localhost:3000/rpc',
  headers: () => ({
    'x-api-key': 'my-api-key'
  }),
  // fetch: <-- polyfill fetch if needed
})

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

Using Client Context

Client context lets you pass extra information when calling procedures and dynamically modify RPCLink’s behavior.

import { router } from './shared/planet'
import { RouterClient } from '@orpc/server'
import { createORPCClient } from '@orpc/client'
import { RPCLink } from '@orpc/client/fetch'

interface ClientContext {
  something?: string
}

const link = new RPCLink<ClientContext>({
  url: 'http://localhost:3000/rpc',
  headers: async ({ context }) => ({
    'x-api-key': context?.something ?? ''
  })
})

const client: RouterClient<typeof router, ClientContext> = createORPCClient(link)

const result = await client.planet.list(
  { limit: 10 },
  { context: { something: 'value' } }
)

INFO

If a property in ClientContext is required, oRPC enforces its inclusion when calling procedures.

Custom Request Method

By default, RPCLink sends requests via POST. You can override this to use methods like GET (for browser or CDN caching) based on your requirements.

import { RPCLink } from '@orpc/client/fetch'

interface ClientContext {
  cache?: RequestCache
}

const link = new RPCLink({
  url: 'http://localhost:3000/rpc',
  method: ({ context }, path) => {
    if (context?.cache) {
      return 'GET'
    }

    if (['get', 'find', 'list', 'search'].includes(path.at(-1)!)) {
      return 'GET'
    }

    return 'POST'
  },
  fetch: (url, init, { context }) =>
    globalThis.fetch(url, { ...init, cache: context?.cache }),
})

Event Source Configuration

Customize the retry logic for event sources using these options:

• eventSourceMaxNumberOfRetries: Maximum retry attempts.
• eventSourceRetryDelay: Delay between retries.
• eventSourceRetry: Function to determine if a retry should occur.

import { RPCLink } from '@orpc/client/fetch'

interface ClientContext {
  eventSourceRetry?: boolean
}

const link = new RPCLink<ClientContext>({
  url: 'http://localhost:3000/rpc',
  eventSourceRetry(reconnectOptions, options, path, input) {
    console.log(reconnectOptions.error)

    return !options.context?.eventSourceRetry
  }
})

TIP

You should disable event source retries when streaming results from a chatbot AI.