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

Note: oRPC support both with and without contract-first development. This guide for without contract-first development.

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 = os.context<Context>()
export const authed = pub.use(({ context, path, next }, input) => {
  /** put auth logic here */
  return next({})
})
 
export const router = pub.router({
  getUser: os
    .input(
      z.object({
        id: z.string(),
      }),
    )
    .handler(async ({ input, context }) => {
      return {
        username: 'example',
        avatar: 'example',
      }
    }),
 
  posts: {
    getPost: pub
      .input(
        z.object({
          id: z.string(),
        }),
      )
      .output(
        z.object({
          id: z.string(),
          title: z.string(),
          description: z.string(),
        }),
      )
      .use(async ({ context, path, next }, input) => {
        if (!context.user) {
          throw new ORPCError({
            code: 'UNAUTHORIZED',
          })
        }
 
        const result = await next({
          context: {
            user: context.user, // from now user not undefined-able
          },
        })
 
        // do something on success
 
        return result
      })
      .handler(({ input, context }) => {
        return {
          id: 'example',
          title: 'example',
          description: 'example',
        }
      }),
 
    createPost: authed
      .input(
        z.object({
          title: z.string(),
          description: z.string(),
          thumb: oz.file().type('image/*'),
        }),
      )
      .handler(async ({ input, context }) => {
        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

import { RPCHandler } from '@orpc/server/node'
import { OpenAPIServerlessHandler } from '@orpc/openapi/node'
import { createServer } from 'node:http'
import { router } from 'examples/server'
import { ZodCoercer } from '@orpc/zod'
 
const openAPIHandler = new OpenAPIServerlessHandler(router, {
  schemaCoercers: [
    new ZodCoercer(),
  ],
})
 
const rpcHandler = new RPCHandler(router)
 
const server = createServer(async (req, res) => {
  if (req.url?.startsWith('/api')) {
    const { matched } = await openAPIHandler.handle(req, res, {
      prefix: '/api',
      context: {},
    })
 
    if(matched){
      return 
    }
  }
 
  if(req.url?.startsWith('/rpc')){
    const { matched } = await rpcHandler.handle(req, res, {
      prefix: '/rpc',
      context: {},
    })
 
    if(matched){
      return 
    }
  }
 
  res.statusCode = 404
  res.end('Not found')
})
 
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 { RPCLink } from '@orpc/client/fetch'
import type { router } from 'examples/server'
 
const rpcLink = new RPCLink({
  url: 'http://localhost:3000/rpc',
  // fetch: optional override for the default fetch function
  // headers: provide additional headers
})
 
const client = createORPCClient<typeof router /* or contract router */>(rpcLink)
 
//  File upload out of the box
const output = await client.posts.createPost({
  title: 'My Amazing Title',
  description: 'This is a detailed description of my content',
  thumb: (document.getElementById('thumb') as HTMLInputElement).files[0]!,
})
 
client.posts.createPost
getPost
 
 
 
 
// typesafe and completion out of box

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