orpc trained

the learned layer: read first.

mental model

oRPC's os builder defines server procedures; a router is a nested object of those procedures. A handler exposes that router, and a link calls it from a client. Contract-first work uses oc and implement; OpenAPI exposure adds route metadata and an OpenAPI handler. Each area has its own guide (core, contract, migration, OpenAPI); check the installed major version before following any of them. The v2 getting started guide is the live API authority.

examples

import { os } from '@orpc/server'
import { z } from 'zod'

const greet = os.input(z.object({ name: z.string() }))
  .handler(({ input }) => `Hello, ${input.name}`)
const router = { greet }

This example is verified against the official docs, not a live install. The procedure guide documents the builder.

best practices

Check the installed @orpc/* version and current docs before copying an API name. Keep oRPC's standard builders and handlers at the call site; do not wrap them in a repo-specific API dialect. Typecheck a real caller and probe both the handler route and client link when changing wire behavior. The v1 migration guide lists silent wire and middleware changes.

strengths

A shared router type gives end-to-end TypeScript calls, while a contract can be shared without server implementation. The same router can be served through RPC and OpenAPI.

weaknesses / pain points

Major-version API and wire changes are consequential. The v2 docs live at orpc.dev; v1 docs live at v1.orpc.dev. A v1 link cannot call a v2 handler. See migration.

gotchas

npm's latest tag for @orpc/server points at 1.x while v2 ships under beta (checked against the registry on 2026-09-27), so a plain install does not select v2; recheck npm view @orpc/server dist-tags --json before installing. RPCLink v2 uses origin plus a path url, and automatic middleware deduplication was removed. See migration.

known bugs

No version-specific implementation defect is known here. The v1/v2 behavior changes above are documented migrations, not bug claims.

troubleshooting

If a v2 example fails against installed 1.x packages, choose the matching version guidance or upgrade all participating @orpc/* packages and client and server together. If a previously shared middleware runs twice after v2, inspect router and procedure registration for duplicate application before adding custom suppression.

Read the orpc skill.