This document provides an introduction to the oRPC framework, explaining its design philosophy, package ecosystem, and core capabilities. oRPC is a TypeScript framework that combines Remote Procedure Call (RPC) functionality with OpenAPI compliance to enable end-to-end type-safe APIs.
This page covers the high-level architecture and package organization. For detailed explanations of fundamental concepts like procedures, routers, and schemas, see Core Concepts. For in-depth architectural patterns and component interactions, see Architecture Overview.
Sources: README.md27-28 README.md31-44
oRPC is a full-stack TypeScript framework for building APIs that are both type-safe and OpenAPI-compliant. It provides dual protocols:
The framework consists of four foundational packages (@orpc/shared, @orpc/contract, @orpc/client, @orpc/server) and an extensive ecosystem of integration packages for schema validation, frontend frameworks, server adapters, and developer tools.
Sources: README.md27-28 README.md67-70 README.md50-65
The oRPC monorepo contains 30+ packages organized into logical categories:
Core Framework Packages:
| Package | Purpose | Key Exports |
|---|---|---|
@orpc/shared | Common utilities and types | AsyncIteratorClass, EventPublisher, stream conversion utilities |
@orpc/contract | Contract definitions | ContractProcedure, ContractRouter, oc builder |
@orpc/client | Client-side consumption | createORPCClient, RPCLink, OpenAPILink |
@orpc/server | Server implementation | Procedure, Router, os builder, RPCHandler, ORPCError |
Sources: pnpm-lock.yaml11-1064 README.md50-65 packages/shared/README.md67-69 packages/contract/README.md67-68 packages/client/README.md67-68 packages/server/README.md67-68
oRPC supports two development approaches:
Example from README.md73-127:
os builder with .input(), .output(), .handler()RPCHandler or OpenAPIHandlerRouterClient<typeof router>Contract definitions use oc builder without handler implementation, enabling parallel frontend/backend development. See Contract-First Development for details.
Sources: README.md67-180 packages/contract/README.md67-102
oRPC uses two parallel builder patterns:
The oc builder creates contracts without implementation, while os builder creates executable procedures. Both support method chaining and can be organized into nested router objects.
Sources: README.md73-127 packages/contract/README.md72-102 packages/server/README.md71-119
The flow demonstrates:
Sources: README.md129-156 packages/client/README.md67-89
oRPC runs on multiple JavaScript runtimes through adapter packages:
Adapter Chain:
@orpc/standard-server: Base interface defining protocol-agnostic contracts@orpc/standard-server-fetch: Implements Fetch API standard (Cloudflare, Vercel, Deno)@orpc/standard-server-node: Extends fetch adapter for Node.js HTTP APIs@orpc/standard-server-fastify: Integrates with Fastify framework@orpc/standard-server-aws-lambda: Transforms Lambda events to standard requests@orpc/standard-server-peer: MessagePort and WebSocket supportSources: pnpm-lock.yaml796-895 README.md43
oRPC provides two protocol handlers with different trade-offs:
| Feature | RPCHandler | OpenAPIHandler |
|---|---|---|
| Protocol | Custom RPC | RESTful OpenAPI 3.1.1 |
| Native Types | Date, File, Blob, BigInt, URL, RegExp | JSON-compatible only |
| Serialization | Efficient binary | JSON |
| Path Structure | /procedure.path | /procedure/path |
| HTTP Methods | POST only | GET, POST, PUT, DELETE, PATCH |
| Third-party Clients | oRPC clients only | Any OpenAPI client |
| Use Case | Type-safe oRPC-to-oRPC | Standards-compliant REST APIs |
Both handlers:
OpenAPIGenerator)Sources: README.md129-156 packages/openapi/README.md67-92
oRPC supports multiple validation libraries through a standard schema interface:
All three libraries:
@standard-schema/spec interface for runtime validation.input() and .output() in both oc and os buildersThe @orpc/zod package provides extended schemas not available in standard Zod:
oz.url(): Native URL objectsoz.blob(): Blob instancesoz.file(): File instances with type constraintsoz.regexp(): RegExp objectsoz.openapi(): Add OpenAPI metadata to any schemaSources: README.md39 packages/zod/README.md67-145 pnpm-lock.yaml266-283 pnpm-lock.yaml977-997 pnpm-lock.yaml1037-1063
oRPC integrates with major frontend data-fetching libraries:
Hub-and-Spoke Pattern:
@orpc/tanstack-query provides framework-agnostic query logic that framework-specific packages extend. Each procedure in the client proxy gains helper methods:
.queryOptions(): Generate TanStack Query options.mutationOptions(): Generate mutation options.infiniteOptions(): Generate infinite query options.key(): Generate query cache keysThis enables type-safe queries with automatic cache key management and input/output inference.
Sources: packages/tanstack-query/package.json1-55 packages/react-query/README.md67-111 packages/vue-query/README.md67-111 packages/vue-colada/README.md67-98
The monorepo includes 12+ playground applications demonstrating integrations:
Web Frameworks:
Special Environments:
Patterns:
Each playground demonstrates complete setup including server handlers, client configuration, and framework-specific integrations.
Sources: pnpm-lock.yaml1065-1170 playgrounds/next/package.json1-30 playgrounds/cloudflare-worker/package.json1-37
Packages prefixed with experimental- explore cutting-edge features:
@orpc/experimental-publisher: Event publishing and pub/sub patterns with Redis/Upstash adapters@orpc/experimental-publisher-durable-object: Distributed pub/sub using Cloudflare Durable Objects@orpc/experimental-ratelimit: Rate limiting with memory, Redis, Upstash, and Cloudflare storage@orpc/experimental-durable-iterator: Resumable streaming with automatic reconnection and state persistenceThese packages demonstrate innovation while the core framework maintains stability. Features may graduate to stable status in future releases.
Sources: pnpm-lock.yaml329-358 pnpm-lock.yaml562-629 README.md60
The monorepo uses modern tooling:
unbuild for consistent package compilation (pnpm-lock.yaml96-98)@antfu/eslint-config with format plugins (pnpm-lock.yaml15-17)bumpp for automated releases (pnpm-lock.yaml57-59)The codebase follows a strict monorepo structure where all packages live in packages/ and examples in playgrounds/.
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.