oRPC: Typesafe APIs Made Simple with RPC and OpenAPI

Introduction

oRPC is a powerful combination of RPC and OpenAPI, designed to make building APIs that are end-to-end type-safe and adhere to OpenAPI standards simple and efficient. It ensures type-safe inputs, outputs, and errors across your entire application stack, from client to server. With oRPC, developers can leverage contract-first development and integrate seamlessly with various frameworks and runtimes, enhancing both developer experience and application reliability.

Installation

To get started with oRPC, you can install the necessary packages using npm or your preferred package manager. The core packages include @orpc/server for backend implementation, @orpc/client for client-side consumption, and @orpc/contract for defining your API structure.

npm install @orpc/server @orpc/client @orpc/contract

Examples

Here's a quick overview of how to use oRPC, from defining your API router to consuming it and generating OpenAPI specifications.

1. Define your router

Start by defining your API procedures and their schemas using a schema validator like Zod.

import type { IncomingHttpHeaders } from 'node:http'
import { ORPCError, os } from '@orpc/server'
import * as z from 'zod'

const PlanetSchema = z.object({
  id: z.number().int().min(1),
  name: z.string(),
  description: z.string().optional(),
})

export const listPlanet = os
  .input(
    z.object({
      limit: z.number().int().min(1).max(100).optional(),
      cursor: z.number().int().min(0).default(0),
    }),
  )
  .handler(async ({ input }) => {
    // your list code here
    return [{ id: 1, name: 'name' }]
  })

export const findPlanet = os
  .input(PlanetSchema.pick({ id: true }))
  .handler(async ({ input }) => {
    // your find code here
    return { id: 1, name: 'name' }
  })

export const createPlanet = os
  .$context<{ headers: IncomingHttpHeaders }>()
  .use(({ context, next }) => {
    const user = parseJWT(context.headers.authorization?.split(' ')[1])

    if (user) {
      return next({ context: { user } })
    }

    throw new ORPCError('UNAUTHORIZED')
  })
  .input(PlanetSchema.omit({ id: true }))
  .handler(async ({ input, context }) => {
    // your create code here
    return { id: 1, name: 'name' }
  })

export const router = {
  planet: {
    list: listPlanet,
    find: findPlanet,
    create: createPlanet
  }
}

2. Create your server

Implement your oRPC server using a runtime-specific handler, for example, Node.js.

import { createServer } from 'node:http'
import { RPCHandler } from '@orpc/server/node'
import { CORSPlugin } from '@orpc/server/plugins'

const handler = new RPCHandler(router, {
  plugins: [new CORSPlugin()]
})

const server = createServer(async (req, res) => {
  const result = await handler.handle(req, res, {
    context: { headers: req.headers }
  })

  if (!result.matched) {
    res.statusCode = 404
    res.end('No procedure matched')
  }
})

server.listen(
  3000,
  '127.0.0.1',
  () => console.log('Listening on 127.0.0.1:3000')
)

3. Create your client

Set up your client to interact with the oRPC server, ensuring type safety on the client side.

import type { RouterClient } from '@orpc/server'
import { createORPCClient } from '@orpc/client'
import { RPCLink } from '@orpc/client/fetch'

const link = new RPCLink({
  url: 'http://127.0.0.1:3000',
  headers: { Authorization: 'Bearer token' },
})

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

4. Consume your API

With the client configured, you can now consume your API with full type safety.

import { orpc } from './client'

const planets = await orpc.planet.list({ limit: 10 })

5. Generate OpenAPI Spec

oRPC allows you to generate OpenAPI specifications directly from your router definition.

import { OpenAPIGenerator } from '@orpc/openapi'
import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'

const generator = new OpenAPIGenerator({
  schemaConverters: [new ZodToJsonSchemaConverter()]
})

const spec = await generator.generate(router, {
  info: {
    title: 'Planet API',
    version: '1.0.0'
  }
})

console.log(spec)

Why Use oRPC?

oRPC offers several compelling advantages for modern API development:

End-to-End Type Safety: Guarantees type-safe data flow from client to server, reducing runtime errors and improving code reliability.
First-Class OpenAPI: Provides native support for OpenAPI standards, simplifying API documentation, discovery, and integration with other tools.
Contract-First Development: Supports defining API contracts before implementation, fostering better collaboration, consistency, and clearer expectations.
Framework Integrations: Offers seamless integration with popular frontend frameworks and data fetching libraries such as TanStack Query, SWR, and Pinia Colada.
Multi-Runtime Support: Designed to be fast and lightweight across various JavaScript runtimes, including Cloudflare Workers, Deno, Bun, and Node.js.
Extendability: Easily extend functionality with a robust plugin system, middleware, and interceptors to tailor oRPC to your specific needs.