This document introduces the oRPC framework and its high-level architecture. It covers the framework's core philosophy, monorepo organization, the four foundational packages, and the dual-protocol approach that distinguishes oRPC from other type-safe API solutions.
For information about defining your first API procedures and handlers, see Getting Started. For details on contract-first development, see Contract-First Development. For the detailed architecture of individual subsystems, see Architecture Overview.
oRPC is a TypeScript-first framework that combines Remote Procedure Call (RPC) with OpenAPI standards to provide end-to-end type safety while maintaining REST compatibility. The framework consists of 50+ packages organized in a monorepo, with four core packages forming the foundation: @orpc/shared, @orpc/contract, @orpc/client, and @orpc/server.
The framework enables developers to define API procedures once and consume them through either a native RPC protocol (optimized for TypeScript-to-TypeScript communication) or standard REST/OpenAPI endpoints (for broader client compatibility).
Sources: README.md27-28 README.md52-65 package.json1-66
The oRPC monorepo uses pnpm workspaces to manage 50+ packages organized into seven functional groups. This structure enables modular consumption—developers install only the packages they need for their specific use case.
Sources: pnpm-lock.yaml1-50 package.json1-66 README.md50-65
The four core packages form a dependency hierarchy, with each package building upon the previous layer. Understanding this structure is essential for comprehending how oRPC achieves end-to-end type safety.
| Package | Primary Classes/Functions | Responsibility |
|---|---|---|
@orpc/shared | EventPublisher, ORPCError, AsyncIteratorClass | Common utilities, error types, stream conversion, event management |
@orpc/contract | oc, ContractProcedure, ContractRouter | API contract definition, schema declarations, route metadata |
@orpc/server | os, Procedure, Router, RPCHandler | Procedure implementation, routing, request handling, middleware |
@orpc/client | createORPCClient, RPCLink, RouterClient | Type-safe client generation, request execution, interceptors |
Sources: packages/shared/package.json1-53 packages/contract/package.json1-52 packages/server/package.json1-154 packages/client/package.json1-74
oRPC's distinguishing feature is its support for two protocols from a single router definition. This allows developers to serve both native TypeScript clients and standard REST consumers without code duplication.
| Aspect | RPC Protocol | OpenAPI Protocol |
|---|---|---|
| Handler | RPCHandler | OpenAPIHandler |
| Client Link | RPCLink | OpenAPILink |
| Serialization | ~serialization (proprietary) | JSON |
| Type Fidelity | Date, BigInt, Set, Map, URL, File preserved | Converted to JSON-compatible (Date → ISO string) |
| HTTP Methods | Always POST | GET, POST, PUT, DELETE, PATCH |
| Use Case | TypeScript ↔ TypeScript communication | Cross-platform, third-party tools, browser-only |
| Performance | Faster (binary format) | Standard (JSON parsing) |
| Compatibility | oRPC clients only | Any HTTP client, OpenAPI tools |
Sources: packages/server/package.json94-110 packages/openapi/package.json54-61 packages/client/package.json49-56 README.md73-199
oRPC uses builder patterns (os for server, oc for contract) to construct procedures with method chaining. The TypeScript compiler infers types at each step, propagating them through the entire request/response cycle.
Example Type Flow:
When a procedure is defined as:
The client automatically infers:
Sources: packages/server/package.json94-110 packages/contract/package.json29-31 README.md84-127
Different use cases require different starting points in the framework. This table maps common scenarios to the appropriate packages and entry functions.
| Use Case | Primary Packages | Entry Point | Imports |
|---|---|---|---|
| Define API procedures | @orpc/server | os builder | import { os } from '@orpc/server' |
| Define contracts first | @orpc/contract | oc builder | import { oc } from '@orpc/contract' |
| Implement contracts | @orpc/server | os.implement() | import { os } from '@orpc/server' |
| Create RPC client | @orpc/client | createORPCClient(RPCLink) | import { createORPCClient } from '@orpc/client'import { RPCLink } from '@orpc/client/fetch' |
| Create REST client | @orpc/openapi-client | createORPCClient(OpenAPILink) | import { OpenAPILink } from '@orpc/openapi-client' |
| Generate OpenAPI spec | @orpc/openapi | OpenAPIGenerator | import { OpenAPIGenerator } from '@orpc/openapi' |
| Serve RPC requests | @orpc/server | RPCHandler | import { RPCHandler } from '@orpc/server/node' |
| Serve REST requests | @orpc/openapi | OpenAPIHandler | import { OpenAPIHandler } from '@orpc/openapi/node' |
| React Query integration | @orpc/react-query | useQuery, useMutation | import { useQuery } from '@orpc/react-query' |
| React Server Actions | @orpc/react | useServerAction | import { useServerAction } from '@orpc/react' |
| Schema validation (Zod) | @orpc/zod | ZodToJsonSchemaConverter | import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4' |
Sources: packages/server/package.json94-110 packages/contract/package.json29-31 packages/client/package.json49-56 packages/openapi/package.json54-61 README.md73-199
This diagram shows how a client request flows through the framework from invocation to response, bridging the natural language concept to actual code entities.
Sources: packages/server/package.json94-110 packages/client/package.json49-56 README.md129-156
The following table summarizes the core concepts that recur throughout the oRPC documentation:
| Concept | Description | Related Page |
|---|---|---|
| Procedure | A single API endpoint with input/output validation and handler logic | Defining Procedures |
| Router | A nested object structure organizing related procedures | Routers and Organization |
| Builder | Method-chaining pattern for constructing procedures (os, oc) | Builder Pattern (os/oc) |
| Contract | Pre-implementation API specification defining inputs/outputs | Contract-First Development |
| Middleware | Functions that intercept and transform requests before handlers | Middleware |
| Plugin | Handler-level extensions for cross-cutting concerns | Plugin System |
| Interceptor | Client-side or server-side hooks for request/response processing | Interceptor Chains |
| Link | Client-side transport layer (RPCLink, OpenAPILink, WebSocketLink) | RPC Client (RPCLink) |
| Handler | Server-side request processor (RPCHandler, OpenAPIHandler) | Server Handlers |
| Schema Converter | Transforms validation schemas to JSON Schema for OpenAPI | Schema Converters |
Sources: packages/server/package.json1-154 packages/contract/package.json1-52 packages/client/package.json1-74 packages/openapi/package.json1-86
oRPC is built on the following technologies and leverages them for specific capabilities:
| Technology | Purpose in oRPC | Package |
|---|---|---|
| TypeScript 5.8+ | Type inference, end-to-end type safety | All packages |
| pnpm workspaces | Monorepo management, dependency resolution | package.json6 |
| unbuild | Package building, dual ESM/CJS output | package.json56 |
| vitest | Testing framework | package.json58 |
| Zod / Valibot / ArkType | Runtime schema validation | @orpc/zod, @orpc/valibot, @orpc/arktype |
| TanStack Query | React/Vue/Svelte data fetching | @orpc/tanstack-query |
| OpenTelemetry | Distributed tracing | @orpc/otel |
| Pino | Structured logging | @orpc/pino |
| rou3 | OpenAPI route matching | packages/openapi/package.json80 |
| VitePress | Documentation site | apps/content/package.json49 |
Sources: package.json1-66 pnpm-lock.yaml1-100 apps/content/package.json1-57
After understanding the framework overview, explore these topics based on your goals:
Sources: README.md46-48 README.md67-199
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.