Quick Start

Introduction

oRPC is a powerful combination of RPC and OpenAPI, offering an exceptional developer experience powered by TypeScript. It's designed to be simple and straightforward to use.

The oRPC ecosystem primarily consists of:

Server

The foundation where you implement your business logic, equipped with numerous utilities for enhanced developer experience.

Client

The interface for communicating with the oRPC server, featuring a fully typed client for seamless integration.

Contract

Enables painless contract-first development approach, ensuring consistent API design.

OpenAPI

Effortlessly publish your API under OpenAPI specification, maintaining industry standards.

Installation

This guide covers the essential server and client components. For additional information, see the Contract Guide and OpenAPI Guide.

npm i @orpc/server @orpc/client

Define Your First Router

import { os, ORPCError, type InferRouterInputs, type InferRouterOutputs } from '@orpc/server'
import { oz } from '@orpc/zod'
import { z } from 'zod'
 
export type Context = { user?: { id: string } }
 
// global pub, authed completely optional
export const pub /** public access */ = os.context<Context>()
export const authed /** require authed */ = pub.use((input, context, meta) => /** put auth logic here */ meta.next({}))
 
export const router = pub.router({
  getting: os
    .input(
      z.object({
        name: z.string(),
      }),
    )
    .func(async (input, context, meta) => {
      return {
        message: `Hello, ${input.name}!`,
      }
    }),
 
  post: {
    find: pub
      .input(
        z.object({
          id: z.string({}),
        }),
      )
      .output(
        z.object({
          id: z.string(),
          title: z.string(),
          description: z.string(),
        }),
      )
      .use(async (input, context, meta) => {
        if (!context.user) {
          throw new ORPCError({
            code: 'UNAUTHORIZED',
          })
        }
 
        const result = await meta.next({
          context: {
            user: context.user, // from now user not undefined-able
          },
        })
 
        // do something on success
 
        return result
      })
      .func((input, context, meta) => {
        return {
          id: 'example',
          title: 'example',
          description: 'example',
        }
      }),
 
    create: authed
      .input(
        z.object({
          title: z.string(),
          description: z.string(),
          thumb: oz.file().type('image/*'),
        }),
      )
      .func(async (input, context, meta) => {
        input.thumb // file upload out of the box
 
        return {
          id: 'example',
          title: input.title,
          description: input.description,
        }
      }),
  },
})
 
export type Inputs = InferRouterInputs<typeof router>
export type Outputs = InferRouterOutputs<typeof router>

In oRPC middleware is very useful and fully typed you can find more info here

Start Your Server

This example uses @whatwg-node/server to create a Node server with Fetch API.

import { handleFetchRequest, createORPCHandler } from '@orpc/server/fetch'
import { createOpenAPIServerlessHandler } from '@orpc/openapi/fetch'
import { createServer } from 'node:http'
import { createServerAdapter } from '@whatwg-node/server'
import { router } from 'examples/server'
 
const server = createServer(
  createServerAdapter((request: Request) => {
    const url = new URL(request.url)
 
    if (url.pathname.startsWith('/api')) {
      return handleFetchRequest({
        router,
        request,
        prefix: '/api',
        context: {},
        handlers: [
          createORPCHandler(),
          createOpenAPIServerlessHandler(),
        ],
      })
    }
 
    return new Response('Not found', { status: 404 })
  }),
)
 
server.listen(3000, () => {
  // eslint-disable-next-line no-console
  console.log('Server is available at http://localhost:3000')
})

Start the server and visit http://localhost:3000/api/getting?name=yourname to see the result.

Client Usage

Use the fully typed client in any environment:

import { createORPCClient, ORPCError } from '@orpc/client'
import type { router } from 'examples/server'
 
const client = createORPCClient<typeof router /* or contract router */>({
  baseURL: 'http://localhost:3000/api',
  // fetch: optional override for the default fetch function
  // headers: provide additional headers
})
 
//  File upload out of the box
const output = await client.post.create({
  title: 'My Amazing Title',
  description: 'This is a detailed description of my content',
  thumb: (document.getElementById('thumb') as HTMLInputElement).files[0]!,
})
 
client.post.create
find
 
 
 
 
// typesafe and completion out of box

That's all you need to get started with oRPC!