-
-
-
-
-
-
- - Typesafe API's Made Simple 🪄 -
-- End-to-End Typesafe API's made easy in a toolkit that helps developers build robust TypeScript API's with a focus on - {' '} - developer experience - , - {' '} - reliability - . -
-
-
- Quick start
-
-
- View on GitHub
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- {/*
-
*/}
-
- End-to-end typesafe APIs
-
-
- First class OpenAPI supports
-
-
- Upload/Download Files supports
-
-
- Framework agnostic
-
-
- Server Actions supports
-
- 
+
+| Name | Description | Customizable |
+| ----------------------- | -------------------------------------------------------------------------------------- | ------------ |
+| **Handler** | Procedures defined with `.handler`. | ✅ |
+| **Middlewares** | Procedures added via `.use`. | ✅ |
+| **Input Validation** | Validates input data against the schema specified in `.input`. | 🟡 |
+| **Output Validation** | Ensures output data conforms to the schema defined in `.output`. | 🟡 |
+| **Client Interceptors** | Interceptors executed before Error Validation. | ✅ |
+| **Error Validation** | Flags errors as defined and validate error data if they match the schema in `.errors`. | 🟡 |
+| **Routing** | Determines which procedure to execute based on the incoming request. | ✅ |
+| **Interceptors** | Interceptors executed before the Error Handler. | ✅ |
+| **Error Handler** | Catches errors and converts them into a response. | 🟡 |
+| **Root Interceptors** | Modify the request or response as needed. | ✅ |
+
+> **Note:** The components _Routing_, _Interceptors_, _Error Handler_, and _Root Interceptors_ are not available when using the [server-side client](/docs/client/server-side).
+
+## Middlewares Order
+
+To ensure that all middlewares run after input validation and before output validation apply the following configuration:
+
+```ts
+const base = os.$config({
+ initialInputValidationIndex: Number.NEGATIVE_INFINITY,
+ initialOutputValidationIndex: Number.NEGATIVE_INFINITY,
+})
+```
+
+:::info
+By default, oRPC executes middlewares based on their registration order relative to validation steps. Middlewares registered before `.input` run before input validation, and those registered after `.output` run before output validation.
+:::
diff --git a/apps/content/docs/middleware.md b/apps/content/docs/middleware.md
new file mode 100644
index 00000000..47fa90b7
--- /dev/null
+++ b/apps/content/docs/middleware.md
@@ -0,0 +1,171 @@
+---
+title: Middleware
+description: Understanding middleware in oRPC
+---
+
+# Middleware in oRPC
+
+Middleware is a powerful feature in oRPC that enables reusable and extensible procedures. It allows you to:
+
+- Intercept, hook into, or listen to a handler's execution.
+- Inject or guard the execution context.
+
+## Overview
+
+Middleware is a function that takes a `next` function as a parameter and either returns the result
+of `next` or modifies the result before returning it.
+
+```ts twoslash
+import { os } from '@orpc/server'
+// ---cut---
+const authMiddleware = os.middleware(async ({ context, next }) => {
+ // Execute logic before the handler
+
+ const result = await next({
+ context: { // Pass additional context
+ user: { id: 1, name: 'John' }
+ }
+ })
+
+ // Execute logic after the handler
+
+ return result
+})
+
+const example = os
+ .use(authMiddleware)
+ .handler(async ({ context }) => {
+ const user = context.user
+ })
+```
+
+## Inline Middleware
+
+Middleware can be defined inline within `.use`, which is useful for simple middleware functions.
+
+```ts
+const example = os
+ .use(async ({ context, next }) => {
+ // Execute logic before the handler
+ return next()
+ })
+ .handler(async ({ context }) => {
+ // Handler logic
+ })
+```
+
+## Middleware Context
+
+Middleware can use to inject or guard the [context](/docs/context).
+
+```ts twoslash
+import { ORPCError, os } from '@orpc/server'
+// ---cut---
+const setting = os
+ .use(async ({ context, next }) => {
+ return next({
+ context: {
+ auth: await auth() // <-- inject auth payload
+ }
+ })
+ })
+ .use(async ({ context, next }) => {
+ if (!context.auth) { // <-- guard auth
+ throw new ORPCError('UNAUTHORIZED')
+ }
+
+ return next({
+ context: {
+ auth: context.auth // <-- override auth
+ }
+ })
+ })
+ .handler(async ({ context }) => {
+ console.log(context.auth) // <-- access auth
+ })
+// ---cut-after---
+declare function auth(): { userId: number } | null
+```
+
+> When you pass additional context to `next`, it will be merged with the existing context.
+
+## Middleware Input
+
+Middleware can access input, enabling use cases like permission checks.
+
+```ts
+const canUpdate = os.middleware(async ({ context, next }, input: number) => {
+ // Perform permission check
+ return next()
+})
+
+const ping = os
+ .input(z.number())
+ .use(canUpdate)
+ .handler(async ({ input }) => {
+ // Handler logic
+ })
+
+// Mapping input if necessary
+const pong = os
+ .input(z.object({ id: z.number() }))
+ .use(canUpdate, input => input.id)
+ .handler(async ({ input }) => {
+ // Handler logic
+ })
+```
+
+## Middleware Output
+
+Middleware can also modify the output of a handler, such as implementing caching mechanisms.
+
+```ts
+const cacheMid = os.middleware(async ({ context, next, path }, input, output) => {
+ const cacheKey = path.join('/') + JSON.stringify(input)
+
+ if (db.has(cacheKey)) {
+ return output(db.get(cacheKey))
+ }
+
+ const result = await next({})
+
+ db.set(cacheKey, result.output)
+
+ return result
+})
+```
+
+## Concatenation
+
+Multiple middleware functions can be combined using `.concat`.
+
+```ts
+const concatMiddleware = aMiddleware
+ .concat(os.middleware(async ({ next }) => next()))
+ .concat(anotherMiddleware)
+```
+
+## Built-in Middlewares
+
+oRPC provides some built-in middlewares that can be used to simplify common use cases.
+
+```ts
+import { onError, onFinish, onStart, onSuccess } from '@orpc/server'
+
+const ping = os
+ .use(onStart(() => {
+ // Execute logic before the handler
+ }))
+ .use(onSuccess(() => {
+ // Execute when the handler succeeds
+ }))
+ .use(onError(() => {
+ // Execute when the handler fails
+ }))
+ .use(onFinish(() => {
+ // Execute logic after the handler
+ }))
+ .handler(async ({ context }) => {
+ // Handler logic
+ })
+```
diff --git a/apps/content/docs/openapi/bracket-notation.md b/apps/content/docs/openapi/bracket-notation.md
new file mode 100644
index 00000000..ef4b7f08
--- /dev/null
+++ b/apps/content/docs/openapi/bracket-notation.md
@@ -0,0 +1,137 @@
+---
+title: Bracket Notation
+description: Represent structured data in limited formats such as URL queries and form data.
+---
+
+# Bracket Notation
+
+Bracket Notation allows you to represent structured data in limited formats such as URL queries and form data.
+It is used with [OpenAPIHandler](/docs/openapi/openapi-handler) and [OpenAPILink](/docs/openapi/client/openapi-link).
+
+## Basic Usage
+
+### URL Query
+
+```bash
+curl http://example.com/api/example?name[first]=John&name[last]=Doe
+```
+
+This query is parsed as:
+
+```json
+{
+ "name": {
+ "first": "John",
+ "last": "Doe"
+ }
+}
+```
+
+### Form Data
+
+```bash
+curl -X POST http://example.com/api/example \
+ -F 'name[first]=John' \
+ -F 'name[last]=Doe'
+```
+
+This form is parsed as:
+
+```json
+{
+ "name": {
+ "first": "John",
+ "last": "Doe"
+ }
+}
+```
+
+## Arrays
+
+Use either empty brackets `[]` or indexed brackets to express arrays. Missing indexes are filled with `null`.
+
+::: warning
+Arrays must contain at least one element.
+:::
+
+```bash
+curl -X POST http://example.com/api/example \
+ -F 'names[]=John' \
+ -F 'names[]=Doe' \
+ -F 'ages[0]=18' \
+ -F 'ages[2]=25'
+```
+
+This query is parsed as:
+
+```json
+{
+ "names": ["John", "Doe"],
+ "ages": [18, null, 25]
+}
+```
+
+## Objects
+
+Wrap keys in brackets to express objects.
+
+::: warning
+
+- Objects must include at least one non-numeric key.
+- Empty objects cannot be represented.
+
+:::
+
+```bash
+curl -X POST http://example.com/api/example \
+ -F 'name[first]=John' \
+ -F 'name[last]=Doe' \
+ -F 'name[nested][first]=John' \
+ -F 'name[nested][last]=Doe'
+```
+
+This query is parsed as:
+
+```json
+{
+ "name": {
+ "first": "John",
+ "last": "Doe",
+ "nested": {
+ "first": "John",
+ "last": "Doe"
+ }
+ }
+}
+```
+
+## Combining Arrays and Objects
+
+You can mix arrays and objects as needed:
+
+```bash
+curl -X POST http://example.com/api/example \
+ -F 'data[names][0][first]=John1' \
+ -F 'data[names][0][last]=Doe1' \
+ -F 'data[names][1][first]=John2' \
+ -F 'data[names][1][last]=Doe2' \
+ -F 'data[ages][0]=18' \
+ -F 'data[ages][2]=25' \
+ -F 'data[files][]=@/path/to/file1' \
+ -F 'data[files][]=@/path/to/file2'
+```
+
+This query is parsed as:
+
+```json
+{
+ "data": {
+ "names": [
+ { "first": "John1", "last": "Doe1" },
+ { "first": "John2", "last": "Doe2" }
+ ],
+ "ages": [18, null, 25],
+ "files": ["...binary data...", "...binary data..."]
+ }
+}
+```
diff --git a/apps/content/docs/openapi/client/openapi-link.md b/apps/content/docs/openapi/client/openapi-link.md
new file mode 100644
index 00000000..dadfb329
--- /dev/null
+++ b/apps/content/docs/openapi/client/openapi-link.md
@@ -0,0 +1,12 @@
+---
+title: OpenAPILink
+description: Details on using OpenAPILink in oRPC clients.
+---
+
+# OpenAPILink
+
+OpenAPILink enables communication with an [OpenAPIHandler](/docs/openapi/openapi-handler) on your server using HTTP/Fetch.
+
+:::info
+Interested in OpenAPILink support? Help us prioritize this feature by casting your vote on [Github](https://github.com/unnoq/orpc/issues/163)
+:::
diff --git a/apps/content/docs/openapi/error-handling.md b/apps/content/docs/openapi/error-handling.md
new file mode 100644
index 00000000..5a6eed63
--- /dev/null
+++ b/apps/content/docs/openapi/error-handling.md
@@ -0,0 +1,56 @@
+---
+title: OpenAPI Error Handling
+description: Handle errors in your OpenAPI-compliant oRPC APIs
+---
+
+# OpenAPI Error Handling
+
+Before you begin, please review our [Error Handling](/docs/error-handling) guide. This document shows you how to align your error responses with OpenAPI standards.
+
+## Default Error Mappings
+
+By default, oRPC maps common error codes to standard HTTP status codes:
+
+| Error Code | HTTP Status Code | Message |
+| ---------------------- | ---------------: | ---------------------- |
+| BAD_REQUEST | 400 | Bad Request |
+| UNAUTHORIZED | 401 | Unauthorized |
+| FORBIDDEN | 403 | Forbidden |
+| NOT_FOUND | 404 | Not Found |
+| METHOD_NOT_SUPPORTED | 405 | Method Not Supported |
+| NOT_ACCEPTABLE | 406 | Not Acceptable |
+| TIMEOUT | 408 | Request Timeout |
+| CONFLICT | 409 | Conflict |
+| PRECONDITION_FAILED | 412 | Precondition Failed |
+| PAYLOAD_TOO_LARGE | 413 | Payload Too Large |
+| UNSUPPORTED_MEDIA_TYPE | 415 | Unsupported Media Type |
+| UNPROCESSABLE_CONTENT | 422 | Unprocessable Content |
+| TOO_MANY_REQUESTS | 429 | Too Many Requests |
+| CLIENT_CLOSED_REQUEST | 499 | Client Closed Request |
+| INTERNAL_SERVER_ERROR | 500 | Internal Server Error |
+| NOT_IMPLEMENTED | 501 | Not Implemented |
+| BAD_GATEWAY | 502 | Bad Gateway |
+| SERVICE_UNAVAILABLE | 503 | Service Unavailable |
+| GATEWAY_TIMEOUT | 504 | Gateway Timeout |
+
+Any error not defined above defaults to HTTP status `500` with the error code used as the message.
+
+## Customizing Errors
+
+You can override the default mappings by specifying a custom `status` and `message` when creating an error:
+
+```ts
+const example = os
+ .errors({
+ RANDOM_ERROR: {
+ status: 503, // <-- override default status
+ message: 'Default error message', // <-- override default message
+ },
+ })
+ .handler(() => {
+ throw new ORPCError('ANOTHER_RANDOM_ERROR', {
+ status: 502, // <-- override default status
+ message: 'Custom error message', // <-- override default message
+ })
+ })
+```
diff --git a/apps/content/docs/openapi/getting-started.md b/apps/content/docs/openapi/getting-started.md
new file mode 100644
index 00000000..14908168
--- /dev/null
+++ b/apps/content/docs/openapi/getting-started.md
@@ -0,0 +1,185 @@
+---
+title: Getting Started with OpenAPI
+description: Quick guide to OpenAPI in oRPC
+---
+
+# Getting Started
+
+OpenAPI is a widely adopted standard for describing RESTful APIs. With oRPC, you can easily publish OpenAPI-compliant APIs with minimal effort.
+
+oRPC is inherently compatible with OpenAPI, but you may need additional configurations such as path prefixes, custom routing, or including headers, parameters, and queries in inputs and outputs. This guide explains how to make your oRPC setup fully OpenAPI-compatible. It assumes basic knowledge of oRPC or familiarity with the [Getting Started](/docs/getting-started) guide.
+
+## Prerequisites
+
+Ensure you have:
+
+- Node.js 18+ (20+ recommended) | Bun | Deno | Cloudflare Workers
+- A package manager: npm | pnpm | yarn | bun | deno
+- A TypeScript project (strict mode recommended)
+
+## Installation
+
+::: code-group
+
+```sh [npm]
+npm install @orpc/server@latest @orpc/client@latest @orpc/openapi@latest
+```
+
+```sh [yarn]
+yarn add @orpc/server@latest @orpc/client@latest @orpc/openapi@latest
+```
+
+```sh [pnpm]
+pnpm add @orpc/server@latest @orpc/client@latest @orpc/openapi@latest
+```
+
+```sh [bun]
+bun add @orpc/server@latest @orpc/client@latest @orpc/openapi@latest
+```
+
+```sh [deno]
+deno install npm:@orpc/server@latest npm:@orpc/client@latest @orpc/openapi@latest
+```
+
+:::
+
+## Defining Routes
+
+This snippet is based on the [Getting Started](/docs/getting-started) guide. Please read it first.
+
+```ts twoslash
+import type { IncomingHttpHeaders } from 'node:http'
+import { ORPCError, os } from '@orpc/server'
+import { z } from 'zod'
+
+const PlanetSchema = z.object({
+ id: z.number().int().min(1),
+ name: z.string(),
+ description: z.string().optional(),
+})
+
+export const listPlanet = os
+ .route({ method: 'GET', path: '/planets' })
+ .input(z.object({
+ limit: z.number().int().min(1).max(100).optional(),
+ cursor: z.number().int().min(0).default(0),
+ }))
+ .output(z.array(PlanetSchema))
+ .handler(async ({ input }) => {
+ // your list code here
+ return [{ id: 1, name: 'name' }]
+ })
+
+export const findPlanet = os
+ .route({ method: 'GET', path: '/planets/{id}' })
+ .input(z.object({ id: z.coerce.number().int().min(1) }))
+ .output(PlanetSchema)
+ .handler(async ({ input }) => {
+ // your find code here
+ return { id: 1, name: 'name' }
+ })
+
+export const createPlanet = os
+ .$context<{ headers: IncomingHttpHeaders }>()
+ .use(({ context, next }) => {
+ const user = parseJWT(context.headers.authorization?.split(' ')[1])
+
+ if (user) {
+ return next({ context: { user } })
+ }
+
+ throw new ORPCError('UNAUTHORIZED')
+ })
+ .route({ method: 'POST', path: '/planets' })
+ .input(PlanetSchema.omit({ id: true }))
+ .output(PlanetSchema)
+ .handler(async ({ input, context }) => {
+ // your create code here
+ return { id: 1, name: 'name' }
+ })
+
+export const router = { planet: { list: listPlanet, find: findPlanet, create: createPlanet } }
+// ---cut-after---
+
+declare function parseJWT(token: string | undefined): { userId: number } | null
+```
+
+### Key Enhancements:
+
+- `.route` defines HTTP methods and paths.
+- `.output` enables automatic OpenAPI spec generation.
+- `z.coerce` ensures correct parameter parsing.
+
+For handling headers, queries, etc., see [Input/Output Structure](/docs/openapi/input-output-structure).
+For auto-coercion, see [Zod Auto Coerce Plugin](/docs/openapi/plugins/zod-auto-coerce).
+For more `.route` options, see [Routing](/docs/openapi/routing).
+
+## Creating a Server
+
+```ts twoslash
+import { router } from './shared/planet'
+// ---cut---
+import { createServer } from 'node:http'
+import { OpenAPIHandler } from '@orpc/openapi/node'
+import { CORSPlugin } from '@orpc/server/plugins'
+
+const handler = new OpenAPIHandler(router, {
+ plugins: [new CORSPlugin()]
+})
+
+const server = createServer(async (req, res) => {
+ const result = await handler.handle(req, res, {
+ context: { headers: req.headers }
+ })
+
+ if (!result.matched) {
+ res.statusCode = 404
+ res.end('No procedure matched')
+ }
+})
+
+server.listen(3000, '127.0.0.1', () => console.log('Listening on 127.0.0.1:3000'))
+```
+
+### Important Changes:
+
+- Use `OpenAPIHandler` instead of `RPCHandler`.
+- Learn more in [OpenAPIHandler](/docs/openapi/openapi-handler).
+
+## Accessing APIs
+
+```bash
+curl -X GET http://127.0.0.1:3000/planets
+curl -X GET http://127.0.0.1:3000/planets/1
+curl -X POST http://127.0.0.1:3000/planets \
+ -H 'Authorization: Bearer token' \
+ -H 'Content-Type: application/json' \
+ -d '{"name": "name"}'
+```
+
+Just a small tweak makes your oRPC API OpenAPI-compliant!
+
+## Generating OpenAPI Spec
+
+Currently, we support Zod for generating OpenAPI specs, but more options will be added soon.
+
+```ts twoslash
+import { OpenAPIGenerator } from '@orpc/openapi'
+import { ZodToJsonSchemaConverter } from '@orpc/zod'
+import { router } from './shared/planet'
+
+const generator = new OpenAPIGenerator({
+ schemaConverters: [new ZodToJsonSchemaConverter()]
+})
+
+const spec = await generator.generate(router, {
+ info: {
+ title: 'Planet API',
+ version: '1.0.0'
+ }
+})
+
+console.log(JSON.stringify(spec, null, 2))
+```
+
+Run the script above to generate your OpenAPI spec.
diff --git a/apps/content/docs/openapi/input-output-structure.md b/apps/content/docs/openapi/input-output-structure.md
new file mode 100644
index 00000000..ac959ddb
--- /dev/null
+++ b/apps/content/docs/openapi/input-output-structure.md
@@ -0,0 +1,105 @@
+---
+title: Input/Output Structure
+description: Control how input and output data is structured in oRPC
+---
+
+# Input/Output Structure
+
+oRPC allows you to control the organization of request inputs and response outputs using the `inputStructure` and `outputStructure` options. This is especially useful when you need to handle parameters, query strings, headers, and body data separately.
+
+## Input Structure
+
+The `inputStructure` option defines how the incoming request data is structured. You can choose between two modes:
+
+- **compact** (default): Merges path parameters with either the query or body data (depending on the HTTP method) into a single object.
+- **detailed**: Separates the request into distinct objects for `params`, `query`, `headers`, and `body`.
+
+### Compact Mode
+
+```ts
+const compactMode = os.route({
+ path: '/ping/{name}',
+ method: 'POST',
+})
+ .input(z.object({
+ name: z.string(),
+ description: z.string().optional(),
+ }))
+```
+
+### Detailed Mode
+
+```ts
+const detailedMode = os.route({
+ path: '/ping/{name}',
+ method: 'POST',
+ inputStructure: 'detailed',
+})
+ .input(z.object({
+ params: z.object({ name: z.string() }),
+ query: z.object({ search: z.string() }),
+ body: z.object({ description: z.string() }).optional(),
+ headers: z.object({ 'content-type': z.string() }),
+ }))
+```
+
+When using **detailed** mode, the input object adheres to the following structure:
+
+```ts
+export type DetailedInput = {
+ params: Record