RPCLink

Enables communication with RPCHandler or any API following the RPC Protocol using HTTP/Fetch.

Overview

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

const link = new RPCLink({
  url: 'http://localhost:3000/rpc',
  headers: () => ({ 'x-api-key': 'my-api-key' }),
  fetch: (request, init) => {
    return globalThis.fetch(request, {
      ...init,
      credentials: 'include',
    })
  },
  interceptors: [onError(e => console.error(e))],
})

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

Using Client Context

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' } }
)

Custom Request Method

interface ClientContext { cache?: RequestCache }

const link = new RPCLink<ClientContext>({
  url: 'http://localhost:3000/rpc',
  method: ({ context }, path) => {
    if (context?.cache) return 'GET'
    if (typeof window === 'undefined') return 'GET'
    if (path.at(-1)?.match(/^(?:get|find|list|search)(?:[A-Z].*)?$/)) return 'GET'
    return 'POST'
  },
  fetch: (request, init, { context }) => globalThis.fetch(request, {
    ...init,
    cache: context?.cache,
  }),
})

Use the contract method automatically:

import { inferRPCMethodFromContractRouter } from '@orpc/contract'

const link = new RPCLink({
  url: 'http://localhost:3000/rpc',
  method: inferRPCMethodFromContractRouter(contract),
})

Lazy URL

const link = new RPCLink({
  url: () => {
    if (typeof window === 'undefined') {
      throw new Error('Not allowed on server')
    }
    return `${window.location.origin}/rpc`
  },
})

Lifecycle

sequenceDiagram
  actor A1 as Client
  participant P1 as Input/Output/Error Encoder
  participant P2 as Client Sender
  participant P3 as Adapter

  A1 ->> P1: input, signal, lastEventId
  P1 ->> P1: encode request
  P1 ->> P2: standard request
  P2 ->> P3: adapter request
  P3 ->> P3: send
  P3 ->> P2: adapter response
  P2 ->> P1: standard response
  P1 ->> P1: decode response
  P1 ->> A1: error/output