RPCLink

RPCLink enables communication with an RPCHandler or any API that follows the RPC Protocol using HTTP/Fetch.

WARNING

This documentation is focused on the HTTP Adapter. Other adapters may remove or change options to keep things simple.

Overview

Before using RPCLink, make sure your server is set up with RPCHandler or any API that follows the RPC Protocol.

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.

WARNING

By default, RPCHandler enabled StrictGetMethodPlugin which blocks GET requests except for procedures explicitly allowed. please refer to StrictGetMethodPlugin for more details.

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

interface ClientContext {
  cache?: RequestCache
}

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

    const lastSegment = path.at(-1)
    if (lastSegment && /get|find|list|search/i.test(lastSegment)) {
      return 'GET'
    }

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

Lazy URL

You can define url as a function, ensuring compatibility with environments that may lack certain runtime APIs.

const link = new RPCLink({
  url: () => {
    if (typeof window === 'undefined') {
      throw new Error('RPCLink is not allowed on the server side.')
    }

    return new URL('/rpc', window.location.href)
  },
})

SSE Like Behavior

Unlike traditional SSE, the Event Iterator does not automatically retry on error. To enable automatic retries, refer to the Client Retry Plugin.

Event Iterator Keep Alive

WARNING

These options for sending Event Iterator from client to the server, not from the server to client as used in RPCHandler Event Iterator Keep Alive or OpenAPIHandler Event Iterator Keep Alive.

In 99% of cases, you don't need to configure these options.

To keep Event Iterator connections alive, RPCLink periodically sends a ping comment to the server. You can configure this behavior using the following options:

• eventIteratorKeepAliveEnabled (default: true) – Enables or disables pings.
• eventIteratorKeepAliveInterval (default: 5000) – Time between pings (in milliseconds).
• eventIteratorKeepAliveComment (default: '') – Custom content for ping messages.

const link = new RPCLink({
  eventIteratorKeepAliveEnabled: true,
  eventIteratorKeepAliveInterval: 5000, // 5 seconds
  eventIteratorKeepAliveComment: '',
})