DOCSEARCHbyAlgolia
Submit Docs

oRPC

website·Indexed 34 days ago

https://orpc.dev/

A framework for building end-to-end typesafe APIs with built-in OpenAPI support. oRPC provides a wide range of adapters for environments including Next.js, Hono, Express, Fastify, Cloudflare Workers, AWS Lambda, Electron, and various browser and worker-based communication methods.

Tokens
95.7K
Snippets
517
Records
586
Agent score
72%

What's inside oRPC

  1. Overview of oRPC Contract-First approach

    Contract-first development in oRPC splits API creation into two steps: defining a contract (a description of procedures, inputs, and outputs without logic) and implementing that contract. This approach is recommended when you need to agree on API design before coding, when the client and server live in different repositories/teams, or when you need a strict source of truth to prevent implementation drift.

  2. Integrate Valibot schemas with oRPC

    Because Valibot implements the Standard Schema specification, oRPC procedures accept Valibot schemas directly without requiring a converter. A converter is only necessary for tools that specifically consume JSON Schema, such as OpenAPI generation or Smart Coercion.

  3. Run oRPC in Expo (General Setup)

    Expo is the supported environment for running oRPC in React Native. To ensure features like JSON calls, AsyncIteratorObject, and streamed downloads work, you need Web Streams (ReadableStream, WritableStream, TransformStream) and a streaming fetch implementation.

    • SDK 56+: Everything works out of the box as expo/fetch replaces the global fetch on Android and iOS.
    • SDK 53 to 55: These versions provide native globals for Web Streams, but you must explicitly pass expo/fetch to your oRPC link because the default React Native fetch does not support streaming.

  4. Update Event Iterator to AsyncIteratorObject

    The 'Event Iterator' concept has been renamed to AsyncIteratorObject. While v1 names remain as deprecated aliases, developers should migrate to the new naming convention.
    import { asyncIteratorObject } from '@orpc/server'

const streaming = os
  .output(asyncIteratorObject(z.object({ message: z.string() })))
  .handler(async function* () {
    yield { message: 'Hello' }
  })

  5. Integrate ArkType with oRPC

    ArkType implements Standard Schema, allowing oRPC procedures to accept ArkType types directly without requiring a converter. A converter is only necessary for tools that specifically consume JSON Schema, such as Smart Coercion or OpenAPI generation.

  6. Use oRPC built-in feature packages

    oRPC offers several specialized utility packages for common backend requirements:

    • @orpc/publisher: Pub/Sub functionality with memory, Redis, and Upstash adapters.
    • @orpc/ratelimit: Rate limiting with memory, Redis, and Upstash adapters.
    • @orpc/experimental-lock: Distributed locking with memory, Redis, and Upstash adapters.
    • @orpc/hibernation: Support for Hibernation APIs (e.g., Cloudflare WebSocket Hibernation).
    • @orpc/json-schema: Provides smart coercion for OpenAPI requests.

  7. Compare oRPC, tRPC, and Hono for TypeScript APIs

    oRPC, tRPC, and Hono all provide end-to-end typesafe APIs in TypeScript but differ in focus:

    • oRPC: Combines typesafe RPC with first-class, native OpenAPI support and a wide range of first-party integrations.
    • tRPC: Focuses primarily on RPC for full-stack TypeScript applications.
    • Hono: A general-purpose web framework that includes an RPC feature.

  8. oRPC Core packages overview

    The core of oRPC is split into four primary packages: @orpc/contract for defining the API contract as the single source of truth; @orpc/server for building APIs and implementing those contracts; @orpc/client for consuming APIs with end-to-end type safety; and @orpc/openapi for adding OpenAPI compatibility to APIs.

  9. Prevent CSRF attacks on GET methods using GetMethodCsrfProtectionHandlerPlugin

    The GetMethodCsrfProtectionHandlerPlugin closes a security gap where browsers attach SameSite=Lax cookies to safe methods like GET during top-level navigations (e.g., link clicks, redirects, or address bar entries).

    It uses Fetch Metadata headers to reject requests with a 403 status if Sec-Fetch-Site is cross-site or none while Sec-Fetch-Mode is navigate and Sec-Fetch-Dest is document.

    Behavior Summary:

    • Rejected: Link clicks, redirects, window.open, GET forms, bookmarks, and links from emails/native apps from another site.
    • Allowed: fetch, XMLHttpRequest, <img>, <script>, media, prefetch, and non-top-level elements like <iframe>.
    • Ignored: Any method other than GET.
    • Always Allowed: Requests from the same site (including sibling subdomains).

    Only requests that match a defined procedure are judged; unmatched requests (e.g., those falling through to a static site) are not affected.

  10. Create an oRPC client

    Use createORPCClient to instantiate a client. You must provide a link (such as an RPC Link or OpenAPI Link) that defines the communication method. Depending on your architecture, you can use either a contract-first approach with RouterContractClient or a normal approach with RouterClient.
    import { createORPCClient } from '@orpc/client'
import { RouterContractClient } from '@orpc/contract'
import { RouterClient } from '@orpc/server'

// Contract-first approach
const contractClient: RouterContractClient<typeof contract> = createORPCClient(link)

// Normal approach
const normalClient: RouterClient<typeof router> = createORPCClient(link)

  11. Configure observability for oRPC

    To implement logging and tracing in oRPC, use the following observability packages:

    • @orpc/opentelemetry: For distributed tracing using OpenTelemetry.
    • @orpc/pino: For logging via Pino.
    • @orpc/evlog: For logging via Evlog.

  12. Access oRPC interactive playgrounds

    oRPC provides pre-configured playgrounds for different environments to help developers explore the library. These are available as interactive StackBlitz projects or as source code on GitHub.