oRPC is a TypeScript RPC framework that combines end-to-end type safety with first-class OpenAPI specification generation. The framework enables developers to define API endpoints using a fluent builder pattern (os for server, oc for contract) while automatically maintaining type safety across client-server boundaries and generating standards-compliant OpenAPI documentation. oRPC supports multiple schema validators (Zod, Valibot, ArkType), runs across edge runtimes and traditional servers, and integrates with modern frontend frameworks through adapters for TanStack Query, SWR, and Pinia Colada.
Sources: README.md1-219 apps/content/blog/v1-announcement.md33-40
This page covers oRPC's fundamental architecture, package ecosystem, and design philosophy. For detailed implementation guidance, see Getting Started. For contract-first development patterns, see Contract-First Development. For package-specific documentation, see Package Ecosystem.
oRPC's design principle is "powerful simplicity" - enabling developers to define API procedures with minimal boilerplate while automatically providing production-grade features. A procedure definition using the os builder resembles a standard function but automatically gains type safety, OpenAPI generation, middleware composition, error handling, and protocol flexibility.
The framework achieves this through a three-tier architecture that separates contract definition, server implementation, and client consumption, allowing each layer to be independently optimized while maintaining end-to-end type inference.
Sources: apps/content/blog/v1-announcement.md32-40 README.md25-44
oRPC Three-Tier Architecture
The architecture consists of three distinct layers:
Contract Layer: The oc builder in @orpc/contract defines API contracts with .input() and .output() methods that accept @standard-schema/spec compliant validators. Contracts form ContractRouter structures that serve as type-safe specifications without implementation details.
Server Layer: The os builder in @orpc/server either implements contracts or defines procedures directly. The .$context<T>() method establishes context typing, .use() composes middleware, and .handler() provides the execution logic. Procedures aggregate into routers (plain objects or EnhancedRouter instances).
Client Layer: The createORPCClient() function in @orpc/client accepts either RPCLink or OpenAPILink adapters and returns a type-safe proxy that mirrors the server router structure. Type information flows from server/contract definitions to client through TypeScript's inference system.
Sources: README.md67-127 packages/server/README.md67-119 packages/contract/README.md67-102 packages/client/README.md67-89
Builder Method Chain
The builder pattern provides a fluent API where each method returns a new builder instance with accumulated configuration. Key methods include:
.$context<T>(): Establishes context type for the procedure chain.use(): Adds middleware that can transform context via next({ context }).input() / .output(): Attaches validation schemas (Zod, Valibot, ArkType).errors(): Defines typed error specifications as an object map.handler(): Provides the procedure implementation with typed { input, context } parameters.route(): Specifies HTTP method and path for OpenAPI generation.meta(): Attaches arbitrary metadata accessible during generation/handling.callable(): Returns a standard async function compatible with React Server Actions.actionable(): Similar to .callable() but designed specifically for form actionsSources: README.md73-127 apps/content/blog/v1-announcement.md42-62
The monorepo at https://github.com/middleapi/orpc contains 50+ packages organized into functional categories:
| Category | Packages | Purpose |
|---|---|---|
| Core | @orpc/shared, @orpc/client, @orpc/contract, @orpc/server, @orpc/openapi | Foundation packages providing builders, handlers, and generators |
| Schema Validators | @orpc/zod, @orpc/valibot, @orpc/arktype | Extensions for schema libraries with OpenAPI converters |
| Server Adapters | @orpc/standard-server* | Platform adapters for Node.js, Fastify, AWS Lambda, fetch API |
| Frontend Integrations | @orpc/react-query, @orpc/vue-query, @orpc/solid-query, @orpc/svelte-query, @orpc/vue-colada, @orpc/experimental-react-swr | Framework-specific query hooks |
| Framework Integration | @orpc/nest, @orpc/react | Deep integrations with NestJS and React Server Actions |
| Observability | @orpc/otel, @orpc/experimental-pino | OpenTelemetry tracing and Pino logging |
| Experimental | @orpc/experimental-durable-iterator, @orpc/experimental-publisher, @orpc/experimental-ratelimit, @orpc/ai-sdk | Advanced features for streaming, pub/sub, rate limiting, AI integration |
| Tooling | @orpc/json-schema, @orpc/openapi-client, @orpc/hey-api | JSON Schema conversion, OpenAPI client generation |
Sources: pnpm-lock.yaml1-1064 README.md50-65
For detailed package documentation, see Package Ecosystem. For core package usage, see Core Packages.
Request Processing Pipeline
Requests flow through a multi-stage pipeline:
Handler Selection: RPCHandler processes RPC protocol requests (typically at /rpc), while OpenAPIHandler processes REST-style OpenAPI requests (path-based routing). Both handlers are initialized with a router and plugins array.
Plugin Execution: Plugins in the plugins array execute during handler initialization via .init() method. Built-in plugins include BatchPlugin (RPC batching), CORSPlugin (CORS headers), RequestHeadersPlugin, ResponseHeadersPlugin, and StrictGetMethodPlugin.
Interceptor Chain: Three interceptor layers execute in order: rootInterceptors, procedure-specific interceptors, and clientInterceptors. Each can transform requests/responses or handle errors.
Middleware & Validation: Middleware added via .use() executes sequentially, followed by input validation (if schema provided), handler execution, and output validation (if schema provided).
Response Serialization: Successful results serialize to { data } format, while errors serialize to { error } format with type information preserved when using .errors().
Sources: README.md129-156 packages/server/README.md67-119 packages/openapi/README.md67-93
For plugin details, see Plugin System. For handler configuration, see Handler Configuration.
Adapter Architecture
The @orpc/standard-server package defines a platform-agnostic interface that adapters implement. The adapter hierarchy follows a layered dependency structure:
http.IncomingMessage and http.ServerResponseBoth RPCHandler and OpenAPIHandler provide runtime-specific exports (e.g., @orpc/server/node, @orpc/openapi/fetch) that use appropriate adapters.
Sources: pnpm-lock.yaml796-895 README.md43
For detailed adapter usage, see Server Adapters.
oRPC generates OpenAPI 3.1.1 specifications through the OpenAPIGenerator class, which accepts schemaConverters to transform Zod, Valibot, and ArkType schemas into JSON Schema. The generator traverses routers/contracts and produces specification objects with paths, components, and security definitions.
The OpenAPIHandler class serves as a REST API endpoint processor that matches incoming HTTP requests against OpenAPI paths and executes corresponding procedures. It automatically serves the OpenAPI specification at a configurable endpoint (default: /openapi.json).
The OpenAPILink client adapter enables consumption of REST/OpenAPI endpoints using the same type-safe client interface as RPC. The @orpc/openapi-client package provides utilities to import external OpenAPI specifications as typed oRPC clients.
Sources: README.md181-199 packages/openapi/README.md67-93
For OpenAPI generation, see Generating OpenAPI Specs. For OpenAPI consumption, see OpenAPI Client.
Framework Integration Architecture
Frontend integration follows a layered approach:
createORPCClient() from @orpc/client creates a type-safe proxy that mirrors router structure@orpc/tanstack-query provides framework-agnostic query/mutation factories that work with TanStack Query implementations@orpc/react-query, @orpc/vue-query, etc.) export hooks that consume the query/mutation factories@orpc/vue-colada integrates with Pinia Colada, @orpc/experimental-react-swr integrates with SWR@orpc/react provides useServerAction() hook and createFormAction() for React Server Actions compatibilityEach integration maintains full type safety from server definition to client usage through TypeScript's type inference.
Sources: packages/tanstack-query/package.json1-55 packages/react-query/README.md67-111 packages/vue-query/README.md67-111 packages/react/README.md67-146
For framework-specific usage, see UI Framework Integrations.
oRPC supports multiple schema validators through the @standard-schema/spec interface. The framework provides three official integrations:
@orpc/zod: Exports oz with additional schemas (URL, Blob, File, RegExp) and ZodToJsonSchemaConverter for OpenAPI generation. Includes oz.openapi() helper for attaching OpenAPI metadata.
@orpc/valibot: Provides ValibotToJsonSchemaConverter using @valibot/to-json-schema for OpenAPI generation.
@orpc/arktype: Provides ArkTypeToJsonSchemaConverter for OpenAPI generation.
Schema converters implement the ConditionalSchemaConverter interface with methods to check compatibility and convert schemas to JSON Schema. The OpenAPIGenerator accepts multiple converters via the schemaConverters array option.
Sources: packages/zod/README.md67-134 pnpm-lock.yaml266-328
For schema usage, see Schema Validation. For converter implementation, see Schema Converters.
The framework includes experimental packages under the experimental- prefix:
@orpc/experimental-durable-iterator: Provides durable event streaming via Cloudflare Durable Objects with automatic reconnection, event recovery, and bi-directional RPC over WebSocket. Exports DurableIteratorObject, DurableIterator, and DurableIteratorLinkPlugin.
@orpc/experimental-publisher: Implements pub/sub patterns with EventPublisher class supporting tag-based filtering and lifecycle hooks (onStart, onSuccess, onError, onFinish).
@orpc/experimental-publisher-durable-object: Extends publisher with Cloudflare Durable Objects support.
@orpc/experimental-ratelimit: Provides rate limiting middleware compatible with Upstash and ioredis.
@orpc/ai-sdk: Integrates with Vercel AI SDK, providing createTool()/implementTool() for tool creation and streaming AI responses as event iterators.
Sources: pnpm-lock.yaml329-359 pnpm-lock.yaml581-630 apps/content/docs/integrations/durable-iterator.md1-445
For experimental features, see Experimental Features.
oRPC provides first-class observability through OpenTelemetry integration:
@orpc/otel: Exports utilities for distributed tracing that integrate with @opentelemetry/api. The package adds spans for procedure execution and automatically captures metadata.
@orpc/experimental-pino: Integrates Pino structured logging with oRPC procedures, providing automatic log context injection.
Both packages work as middleware/interceptors that can be added to any procedure or handler.
Sources: pnpm-lock.yaml533-560 README.md36
For OpenTelemetry integration, see OpenTelemetry Integration. For logging, see Logging Integrations.
The oRPC ecosystem includes community-developed tools and starter kits:
Starter Kits: Zap.ts, Better-T-Stack, create-o3-app, RT Stack, Start UI, ShipFullStack provide pre-configured project templates with oRPC integration.
Tools: orpc-file-based-router (file-based routing), Vertrag (spec-first development), prisma-orpc-generator (Prisma integration), DRZL (Drizzle codegen), orpc-msw (MSW mocking).
Libraries: Permix (permissions), trpc-cli (CLI generation), @reliverse/rempts (CLI toolkit), oRPC Shield (authorization), Every Plugin (plugin runtime), orpc-json-diff (JSON patch streaming), effect-orpc (Effect-TS integration).
Sources: apps/content/docs/ecosystem.md1-47
For playground examples, see Examples and Playgrounds. For development setup, see Development Guide.
Refresh this wiki