Overview

Relevant source files

• README.md
• apps/content/package.json
• packages/client/README.md
• packages/contract/README.md
• packages/durable-iterator/package.json
• packages/openapi/README.md
• packages/react-query/README.md
• packages/react/README.md
• packages/server/README.md
• packages/shared/README.md
• packages/solid-query/package.json
• packages/svelte-query/package.json
• packages/tanstack-query/package.json
• packages/vue-colada/README.md
• packages/vue-query/README.md
• packages/zod/README.md
• playgrounds/astro/package.json
• playgrounds/browser-extension/package.json
• playgrounds/bun-websocket-otel/package.json
• playgrounds/cloudflare-worker/package.json
• playgrounds/contract-first/package.json
• playgrounds/electron/package.json
• playgrounds/nest/package.json
• playgrounds/next/package.json
• playgrounds/svelte-kit/package.json
• playgrounds/tanstack-start/package.json
• pnpm-lock.yaml

Purpose and Scope

oRPC is a TypeScript RPC framework that combines end-to-end type safety with first-class OpenAPI support. The framework enables building APIs that are fully type-safe from client to server while remaining compatible with the OpenAPI 3.1.1 specification. This dual-protocol design allows the same business logic to be consumed both through an efficient proprietary RPC protocol and a standard RESTful OpenAPI interface.

This page provides a high-level overview of the oRPC framework architecture, monorepo structure, and core systems. For detailed information about specific subsystems, refer to:

• Contract and server definitions: #3, #4
• Schema validation: #5
• OpenAPI integration: #6
• Client usage: #7
• Platform adapters: #9
• Framework integrations: #10

Sources: README.md1-219 packages/shared/README.md1-82

Monorepo Structure

The oRPC repository is organized as a monorepo containing approximately 40+ packages divided into logical subsystems. The following diagram shows the high-level organization:

Package Categories

Category	Packages	Purpose
Core	@orpc/shared, @orpc/contract, @orpc/client, @orpc/server	Foundational packages providing base utilities, contract definitions, client implementation, and server implementation
Schema Validation	@orpc/zod, @orpc/valibot, @orpc/arktype	Adapters for schema validation libraries with JSON Schema conversion
OpenAPI	@orpc/openapi, @orpc/openapi-client, @orpc/json-schema	OpenAPI 3.1.1 specification generation and REST API handling
Server Adapters	@orpc/standard-server-*	Progressive server adapters for different runtimes and frameworks
Framework Integrations	@orpc/react-query, @orpc/vue-query, @orpc/nest, etc.	Integration with frontend and backend frameworks
Experimental	@orpc/ai-sdk, @orpc/experimental-publisher, @orpc/experimental-ratelimit, etc.	Advanced features for AI, pub/sub, rate limiting, and observability

Sources: pnpm-lock.yaml1-1064 README.md50-66

Core Architecture

The core architecture consists of four foundational packages that work together to enable type-safe RPC communication:

@orpc/shared

Provides shared utilities used across all packages:

• Type utilities: InferSchemaInput, InferSchemaOutput, type manipulation helpers
• Stream conversion: eventIteratorToStream, streamToEventIterator
• Error handling: ORPCError class
• Common helper functions from radash and type-fest

@orpc/contract

Enables contract-first development with the oc builder:

• ContractProcedure: Defines procedure contracts with input/output schemas
• ContractRouter: Organizes contract procedures into routers
• Implements @standard-schema/spec interface for schema validation
• Supports schema validation with Zod, Valibot, ArkType, and other libraries

@orpc/client

Implements the client-side RPC functionality:

• createORPCClient(): Factory function for creating type-safe clients
• RPCLink: Proprietary RPC protocol client for efficient communication
• OpenAPILink: REST-compatible client for OpenAPI endpoints
• Client-side interceptor chain for request/response modification
• Dynamic context injection via ClientContext

@orpc/server

Implements the server-side procedure and router system:

• os builder: Fluent API for defining procedures with middleware
• Procedure: Server-side procedure implementation with handler logic
• Router: Hierarchical organization of procedures
• RPCHandler: Processes proprietary RPC protocol requests
• Middleware system for context enrichment and validation
• Plugin architecture for extensibility

Sources: packages/shared/package.json1-56 packages/contract/package.json1-328 packages/client/package.json1-302 packages/server/package.json1-751 README.md52-66

Dual Protocol Architecture

oRPC supports two distinct communication protocols that share the same business logic layer:

RPC Protocol

The proprietary RPC protocol prioritizes type fidelity and efficiency:

• Preserves native JavaScript types: Date, BigInt, RegExp, URL, Set, Map, Blob, File
• Handles edge cases: NaN, Invalid Date, Infinity
• Uses StandardRPCLinkCodec for efficient serialization
• Ideal for TypeScript-to-TypeScript microservices communication
• Accessed via RPCLink on the client and RPCHandler on the server

OpenAPI Protocol

The OpenAPI protocol ensures universal compatibility:

• Converts complex types to JSON-compatible formats
• BigInt → string, Set → array, NaN → null
• Supports multipart/form-data for file uploads
• Adheres to OpenAPI 3.1.1 specification
• Accessed via OpenAPILink on the client and OpenAPIHandler on the server
• Generates OpenAPI specifications via OpenAPIGenerator

Both protocols converge at the Router layer, allowing the same business logic to be exposed through multiple protocols without duplication.

Sources: packages/client/package.json285-302 packages/openapi/package.json477-512

Schema Validation System

oRPC implements a pluggable schema validation architecture that supports multiple validation libraries:

Each schema adapter implements:

• The @standard-schema/spec interface for runtime validation
• Conversion to JSON Schema for OpenAPI specification generation
• Library-specific extensions and features

This design allows developers to choose their preferred validation library without framework lock-in. New validation libraries can be integrated by creating adapters that implement the standard schema interface.

Sources: packages/zod/package.json1-1063 packages/valibot/package.json977-997 packages/arktype/package.json266-283 packages/contract/package.json312-314

Framework Integration Architecture

oRPC integrates with multiple frontend frameworks using a hub-and-spoke pattern centered on @orpc/tanstack-query:

Hub-and-Spoke Benefits

• Code Reuse: Core data fetching logic resides in @orpc/tanstack-query
• Consistency: All frameworks share the same query/mutation behavior
• Maintainability: Framework-specific code is minimal and isolated
• Flexibility: Easy to add new framework integrations

The framework-specific packages provide thin wrappers that handle only framework-specific concerns like reactivity systems and lifecycle hooks.

Sources: packages/tanstack-query/package.json1-55 packages/react-query/package.json1-677 packages/vue-query/package.json1-1036 packages/solid-query/package.json1-795 packages/svelte-query/package.json1-917 packages/react/package.json631-655 packages/vue-colada/package.json999-1017

Server Adapter Deployment Chain

oRPC uses a progressive enhancement pattern for server adapters, enabling deployment across diverse runtime environments:

Adapter Layering

Layer	Packages	Target Environments
Base	@orpc/standard-server	Abstract interface for all adapters
Web Standards	@orpc/standard-server-fetch, @orpc/standard-server-peer	Cloudflare Workers, Deno, Bun, browsers, P2P networks
Node.js	@orpc/standard-server-node	Node.js HTTP servers
Frameworks	@orpc/standard-server-fastify, @orpc/standard-server-aws-lambda	Fastify applications, AWS Lambda functions

This layered approach means simpler adapters don't carry unnecessary dependencies, while complex adapters inherit the full capability stack. Developers can deploy the same business logic across 10+ runtime environments without code changes.

Sources: packages/standard-server/package.json796-801 packages/standard-server-fetch/package.json852-864 packages/standard-server-node/package.json865-886 packages/standard-server-fastify/package.json824-851 packages/standard-server-aws-lambda/package.json802-823 packages/standard-server-peer/package.json887-895

Experimental Features

Experimental packages extend oRPC's capabilities for advanced distributed systems use cases:

Experimental Package Categories

Package	Purpose
@orpc/ai-sdk	Integration with Vercel AI SDK for tool creation and streaming
@orpc/experimental-publisher	Event publishing with Redis/Upstash backends
@orpc/experimental-publisher-durable-object	Cloudflare Durable Objects for distributed stateful pub/sub
@orpc/experimental-ratelimit	Pluggable rate limiting with memory, Redis, Upstash, and Cloudflare adapters
@orpc/experimental-durable-iterator	WebSocket-based durable iterators for Cloudflare Workers
@orpc/otel	OpenTelemetry integration for distributed tracing
@orpc/pino	Pino structured logging integration

These packages are marked "experimental" but provide production-ready capabilities for AI, real-time communication, and distributed systems concerns.

Sources: packages/ai-sdk/package.json244-264 packages/publisher/package.json562-580 packages/publisher-durable-object/package.json581-605 packages/ratelimit/package.json606-630 packages/durable-iterator/package.json1-61 packages/otel/package.json533-545 packages/pino/package.json546-561

Development Workflow

The oRPC monorepo uses modern tooling for efficient development:

Build and Quality Tools

Tool	Purpose
unbuild	Compiles TypeScript to ES modules with minimal configuration
tsc -b	Type checking separate from compilation for speed
vitest	Fast unit testing with native ESM support
@antfu/eslint-config	Consistent code style across packages
sherif	Validates dependency versions and workspace consistency
knip	Detects unused exports and dependencies
bumpp	Version bumping with changelog generation
changelogithub	Generates changelogs from GitHub releases
pkg-pr-new	Preview package publishing for pull requests

The monorepo uses pnpm with workspace linking, allowing packages to reference each other via workspace:* specifiers. This enables rapid iteration without publishing intermediate versions.

Sources: pnpm-lock.yaml1-1064 package.json not shown but inferred from lock file

Playgrounds and Documentation

The monorepo includes extensive playgrounds demonstrating real-world usage:

Playground	Framework/Runtime	Key Features
playgrounds/next	Next.js	React Server Actions, API routes
playgrounds/svelte-kit	SvelteKit	Server-side rendering, form actions
playgrounds/astro	Astro	Partial hydration, React integration
playgrounds/cloudflare-worker	Cloudflare Workers	Durable Objects, pub/sub
playgrounds/electron	Electron	Desktop app, IPC communication
playgrounds/nest	NestJS	Dependency injection, decorators
playgrounds/contract-first	Node.js	Contract-first development workflow
playgrounds/browser-extension	Browser Extension	Background scripts, content scripts
playgrounds/bun-websocket-otel	Bun	WebSocket, OpenTelemetry tracing
playgrounds/tanstack-start	TanStack Start	Full-stack React framework

Documentation is built with VitePress and includes:

• @shikijs/vitepress-twoslash for interactive TypeScript code samples
• vitepress-plugin-mermaid for diagram rendering
• markdown-it-task-lists for task list support
• vitepress-plugin-llms for LLM-friendly documentation format

Sources: playgrounds/next/package.json1-30 playgrounds/svelte-kit/package.json1-32 playgrounds/astro/package.json1-31 playgrounds/cloudflare-worker/package.json1-37 playgrounds/electron/package.json1-38 playgrounds/nest/package.json1-40 playgrounds/contract-first/package.json1-25 playgrounds/browser-extension/package.json1-34 playgrounds/bun-websocket-otel/package.json1-36 playgrounds/tanstack-start/package.json1-36 apps/content/package.json1-57