oRPC: contract-first, end-to-end typesafe APIs in TypeScript

The contract package is the whole idea

Most TypeScript RPC libraries make the server the source of truth and infer the client types from it. That works until a second consumer appears: a mobile app, a background worker, a partner team. Then the client has to depend on the server package, or the types get copied by hand.

oRPC splits the definition out. @orpc/contract holds the API shape as a standalone artifact. @orpc/server implements it. @orpc/client consumes it. The README describes the contract as "the single source of truth", and the package list makes that literal: three separate npm packages, each installable on its own. A frontend repository can depend on @orpc/contract and @orpc/client without pulling in the server runtime at all.

This is the design decision worth judging. It costs you a third package in the dependency graph and a build step that has to publish the contract somewhere both sides can resolve. In exchange, the boundary between what the API promises and how it is implemented becomes a file rather than a convention.

Where oRPC sits next to tRPC, and why @orpc/trpc exists

The most common question about this project is whether it beats tRPC. The honest answer depends on whether you need the contract to exist outside the server.

tRPC's model is a router on the server, with the client inferring types from the router's type. It is a shorter path from zero to a working typed call, and the inference is the feature. oRPC's model inserts the contract in the middle, and then adds a second capability tRPC does not ship in the same package: @orpc/openapi produces OpenAPI compatibility from the same procedures, so a non-TypeScript consumer can call the API through a generated document.

The repository also lists @orpc/trpc, described as reusing existing tRPC routers within oRPC. That is a migration path rather than a rewrite: keep the routers you have, and put oRPC's contract and OpenAPI layer in front of them. If your API is TypeScript-only and will stay that way, that extra layer is overhead you are choosing to pay.

Installing oRPC and getting one typed call through

The README points to orpc.dev for documentation and does not include install commands, so the package names below come from the README's package list and the versions come from npm. The monorepo itself is private and pins pnpm in devEngines, which matters only if you are building from source rather than installing.

Start with the three core packages:

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

Add a schema adapter for whichever validation library you already use. The README lists Zod, Valibot and ArkType as separate packages:

npm install @orpc/zod

If the API has to be callable from outside TypeScript, add the OpenAPI package as well:

npm install @orpc/openapi

What you should see after this is three or four entries in package.json under dependencies, with the versions npm resolved. The contract, server and client packages are versioned together, so check that they landed on the same version before you write any code. The README does not document a CLI, a code generator, or a project scaffold, so there is no init command to run; the shape of a contract is defined in the documentation site, not in the repository README.

Smart coercion in @orpc/json-schema, and what it is for

The README's one-line description of @orpc/json-schema is "Smart coercion for OpenAPI requests". That is a narrow job and an easy one to overlook.

HTTP query strings and path parameters are strings. A schema that expects a number or a boolean will reject "42" and "true" unless something converts them first. Coercion is the layer that decides whether ?limit=10 arrives at your handler as 10 or as "10", and whether an empty query parameter becomes undefined or an empty string.

Placing that concern in a separate package rather than inside the OpenAPI integration is a reasonable split: the coercion rules are the part most likely to need adjusting per project, and keeping them out of @orpc/openapi means you can change them without touching the document generation. The README does not describe the coercion rules themselves, so the specifics have to come from orpc.dev. Treat the package name as a pointer, not a specification.

The beta channel is the real adoption cost

The most recent releases are v2.0.0-beta.31, v2.0.0-beta.30 and v2.0.0-beta.29, dated 2026-08-23, 2026-08-21 and 2026-08-20. Three betas in four days. The last push to the repository was on 2026-08-23.

That cadence tells you two things. Development is current, and the 2.0 line is not finished. A beta that ships every day or two is a moving target: pinning "^2.0.0-beta.31" in package.json can pull behaviour you did not read about, and the gap between what the docs describe and what the installed package does is widest during a beta run.

If you are already on a 1.x line, the decision is whether to wait for 2.0.0 to leave beta or to absorb the churn now. The repository does not include a changelog in the files available, and the README does not document rollback or a downgrade path, so the migration notes on orpc.dev are the only place to confirm what changed between betas.

Integrations, and the ones marked experimental

The package list is long, and the naming tells you which parts carry more risk. @orpc/experimental-msw, @orpc/experimental-effect and @orpc/experimental-lock are prefixed experimental. @orpc/experimental-msw mocks procedures with Mock Service Worker, @orpc/experimental-effect integrates with Effect, and @orpc/experimental-lock appears in the monorepo's devDependencies but is not described in the README's package list.

The non-experimental integrations cover the common ground: @orpc/tanstack-query, @orpc/swr and @orpc/pinia-colada for data fetching, @orpc/next for Next.js Server Functions, @orpc/nest for NestJS, @orpc/ai-sdk for turning contracts into AI SDK tools, and @orpc/opentelemetry, @orpc/pino and @orpc/evlog for tracing and logging. Built-in feature packages cover pub/sub, rate limiting and Cloudflare's Hibernation WebSocket API.

For an OpenAPI-first team, @orpc/json-schema is the package to look at first. For a team that only needs typed calls between a Next.js app and its own backend, the integration packages are mostly optional weight.

Licence, maintenance and what upgrading costs you

oRPC is MIT licensed, per the LICENSE file at the repository root. That permits commercial use and modification, but it is worth checking the licence of each schema adapter you add: Zod, Valibot and ArkType are separate projects with their own terms, and the MIT licence on oRPC says nothing about them.

Maintenance looks current rather than settled. The repository is not archived, the last push was on 2026-08-23, and the release cadence is measured in days. The monorepo pins pnpm ^12.4.1 through devEngines and requires it to build from source. The .env.example notes that some project tests depend on Redis or Upstash Redis and provides REDIS_URL, UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN for that purpose, which tells you the test suite reaches outside the process for anything touching the publisher or rate limit packages.

The upgrade cost is concentrated in the beta. Every minor bump inside 2.0.0-beta can change behaviour, and because the contract package is a shared artifact, a breaking change there propagates to every consumer at once. Budget for reading release notes before each bump rather than after.

Editorial conclusion

Adopt oRPC if you want one contract package that a TypeScript server and its clients both import, and if you need an OpenAPI document produced from the same procedures. Do not adopt it for a small internal app where a single server file and a tRPC-style client would do, and do not adopt it if you cannot tolerate tracking 2.0.0-beta releases. Before committing, check the exact version of @orpc/contract, @orpc/server and @orpc/client on npm, and read the migration notes for 2.0.0 on orpc.dev to confirm which beta behaviour you are pinning.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes