From 3bbc8bb63e7b37cc475ecc5906df059808634f37 Mon Sep 17 00:00:00 2001 From: unnoq Date: Wed, 29 Oct 2025 10:01:38 +0700 Subject: [PATCH] docs: recommend use onError in handlers --- apps/content/docs/adapters/astro.md | 11 +++- apps/content/docs/adapters/browser.md | 33 +++++++++--- apps/content/docs/adapters/electron.md | 11 +++- apps/content/docs/adapters/elysia.md | 13 +++-- apps/content/docs/adapters/express.md | 9 +++- apps/content/docs/adapters/h3.md | 9 +++- apps/content/docs/adapters/hono.md | 9 +++- apps/content/docs/adapters/http.md | 54 ++++++++++++++++--- apps/content/docs/adapters/message-port.md | 9 +++- apps/content/docs/adapters/next.md | 22 ++++++-- apps/content/docs/adapters/nuxt.md | 11 +++- apps/content/docs/adapters/remix.md | 11 +++- apps/content/docs/adapters/solid-start.md | 11 +++- apps/content/docs/adapters/svelte-kit.md | 11 +++- apps/content/docs/adapters/tanstack-start.md | 9 +++- apps/content/docs/adapters/web-workers.md | 11 +++- apps/content/docs/adapters/websocket.md | 53 ++++++++++++++---- apps/content/docs/adapters/worker-threads.md | 11 +++- apps/content/docs/getting-started.md | 8 ++- apps/content/docs/openapi/getting-started.md | 8 ++- .../content/docs/openapi/integrations/trpc.md | 4 +- apps/content/docs/openapi/openapi-handler.md | 4 +- 22 files changed, 277 insertions(+), 55 deletions(-) diff --git a/apps/content/docs/adapters/astro.md b/apps/content/docs/adapters/astro.md index 05a0a1364..2a3c8aa2a 100644 --- a/apps/content/docs/adapters/astro.md +++ b/apps/content/docs/adapters/astro.md @@ -13,8 +13,15 @@ description: Use oRPC inside an Astro project ```ts [pages/rpc/[...rest].ts] import { RPCHandler } from '@orpc/server/fetch' - -const handler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) export const prerender = false diff --git a/apps/content/docs/adapters/browser.md b/apps/content/docs/adapters/browser.md index 186c99f50..6fc574176 100644 --- a/apps/content/docs/adapters/browser.md +++ b/apps/content/docs/adapters/browser.md @@ -19,8 +19,15 @@ The browser extension [Message Passing API](https://developer.chrome.com/docs/ex ```ts [server] import { RPCHandler } from '@orpc/server/message-port' - -const handler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) browser.runtime.onConnect.addListener((port) => { handler.upgrade(port, { @@ -53,8 +60,15 @@ To enable communication between two window contexts (e.g. parent and popup), one ```ts [opener] import { RPCHandler } from '@orpc/server/message-port' - -const handler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) window.addEventListener('message', (event) => { if (event.data instanceof MessagePort) { @@ -123,8 +137,15 @@ window.addEventListener('message', (event) => { ```ts [server] import { RPCHandler } from '@orpc/server/message-port' - -const handler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) browser.runtime.onConnect.addListener((port) => { handler.upgrade(port, { diff --git a/apps/content/docs/adapters/electron.md b/apps/content/docs/adapters/electron.md index bc61f5511..fb76c1b2a 100644 --- a/apps/content/docs/adapters/electron.md +++ b/apps/content/docs/adapters/electron.md @@ -13,8 +13,15 @@ Listen for a port sent from the renderer, then upgrade it: ```ts import { RPCHandler } from '@orpc/server/message-port' - -const handler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) app.whenReady().then(() => { ipcMain.on('start-orpc-server', async (event) => { diff --git a/apps/content/docs/adapters/elysia.md b/apps/content/docs/adapters/elysia.md index 61d467336..d21bab808 100644 --- a/apps/content/docs/adapters/elysia.md +++ b/apps/content/docs/adapters/elysia.md @@ -11,9 +11,16 @@ description: Use oRPC inside an Elysia project ```ts import { Elysia } from 'elysia' -import { OpenAPIHandler } from '@orpc/openapi/fetch' - -const handler = new OpenAPIHandler(router) +import { RPCHandler } from '@orpc/server/fetch' +import { onError } from '@orpc/server' + +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) const app = new Elysia() .all('/rpc*', async ({ request }: { request: Request }) => { diff --git a/apps/content/docs/adapters/express.md b/apps/content/docs/adapters/express.md index 371fab5e8..a15d1d9f1 100644 --- a/apps/content/docs/adapters/express.md +++ b/apps/content/docs/adapters/express.md @@ -17,12 +17,19 @@ Express's [body-parser](https://expressjs.com/en/resources/middleware/body-parse import express from 'express' import cors from 'cors' import { RPCHandler } from '@orpc/server/node' +import { onError } from '@orpc/server' const app = express() app.use(cors()) -const handler = new RPCHandler(router) +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) app.use('/rpc{/*path}', async (req, res, next) => { const { matched } = await handler.handle(req, res, { diff --git a/apps/content/docs/adapters/h3.md b/apps/content/docs/adapters/h3.md index 37cacaf53..970449755 100644 --- a/apps/content/docs/adapters/h3.md +++ b/apps/content/docs/adapters/h3.md @@ -12,10 +12,17 @@ description: Use oRPC inside an H3 project ```ts import { H3, serve } from 'h3' import { RPCHandler } from '@orpc/server/fetch' +import { onError } from '@orpc/server' const app = new H3() -const handler = new RPCHandler(router) +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) app.use('/rpc/**', async (event) => { const { matched, response } = await handler.handle(event.req, { diff --git a/apps/content/docs/adapters/hono.md b/apps/content/docs/adapters/hono.md index b4fa986e2..464595115 100644 --- a/apps/content/docs/adapters/hono.md +++ b/apps/content/docs/adapters/hono.md @@ -12,10 +12,17 @@ description: Use oRPC inside an Hono project ```ts import { Hono } from 'hono' import { RPCHandler } from '@orpc/server/fetch' +import { onError } from '@orpc/server' const app = new Hono() -const handler = new RPCHandler(router) +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) app.use('/rpc/*', async (c, next) => { const { matched, response } = await handler.handle(c.req.raw, { diff --git a/apps/content/docs/adapters/http.md b/apps/content/docs/adapters/http.md index ba1929074..e9a64d100 100644 --- a/apps/content/docs/adapters/http.md +++ b/apps/content/docs/adapters/http.md @@ -22,11 +22,17 @@ oRPC includes built-in HTTP support, making it easy to expose RPC endpoints in a import { createServer } from 'node:http' // or 'node:http2' import { RPCHandler } from '@orpc/server/node' import { CORSPlugin } from '@orpc/server/plugins' +import { onError } from '@orpc/server' const handler = new RPCHandler(router, { plugins: [ new CORSPlugin() - ] + ], + interceptors: [ + onError((error) => { + console.error(error) + }), + ], }) const server = createServer(async (req, res) => { @@ -49,11 +55,17 @@ server.listen(3000, '127.0.0.1', () => console.log('Listening on 127.0.0.1:3000' ```ts [bun] import { RPCHandler } from '@orpc/server/fetch' import { CORSPlugin } from '@orpc/server/plugins' +import { onError } from '@orpc/server' const handler = new RPCHandler(router, { plugins: [ new CORSPlugin() - ] + ], + interceptors: [ + onError((error) => { + console.error(error) + }), + ], }) Bun.serve({ @@ -75,11 +87,17 @@ Bun.serve({ ```ts [cloudflare] import { RPCHandler } from '@orpc/server/fetch' import { CORSPlugin } from '@orpc/server/plugins' +import { onError } from '@orpc/server' const handler = new RPCHandler(router, { plugins: [ new CORSPlugin() - ] + ], + interceptors: [ + onError((error) => { + console.error(error) + }), + ], }) export default { @@ -101,11 +119,17 @@ export default { ```ts [deno] import { RPCHandler } from '@orpc/server/fetch' import { CORSPlugin } from '@orpc/server/plugins' +import { onError } from '@orpc/server' const handler = new RPCHandler(router, { plugins: [ new CORSPlugin() - ] + ], + interceptors: [ + onError((error) => { + console.error(error) + }), + ], }) Deno.serve(async (request) => { @@ -125,8 +149,15 @@ Deno.serve(async (request) => { ```ts [fastify] import Fastify from 'fastify' import { RPCHandler } from '@orpc/server/fastify' - -const rpcHandler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const rpcHandler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) const fastify = Fastify() @@ -152,8 +183,15 @@ fastify.listen({ port: 3000 }).then(() => console.log('Listening on 127.0.0.1:30 ```ts [aws-lambda] import { APIGatewayProxyEventV2 } from 'aws-lambda' import { RPCHandler } from '@orpc/server/aws-lambda' - -const rpcHandler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const rpcHandler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) /** * oRPC only supports [AWS Lambda response streaming](https://aws.amazon.com/blogs/compute/introducing-aws-lambda-response-streaming/). diff --git a/apps/content/docs/adapters/message-port.md b/apps/content/docs/adapters/message-port.md index 3a17810b3..602e1be1f 100644 --- a/apps/content/docs/adapters/message-port.md +++ b/apps/content/docs/adapters/message-port.md @@ -25,8 +25,15 @@ const clientPort = channel.port2 ```ts [server] import { RPCHandler } from '@orpc/server/message-port' +import { onError } from '@orpc/server' -const handler = new RPCHandler(router) +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) handler.upgrade(serverPort, { context: {}, // Provide initial context if needed diff --git a/apps/content/docs/adapters/next.md b/apps/content/docs/adapters/next.md index 63cf574fb..ec67e3b81 100644 --- a/apps/content/docs/adapters/next.md +++ b/apps/content/docs/adapters/next.md @@ -19,8 +19,15 @@ You set up an oRPC server inside Next.js using its [Route Handlers](https://next ```ts [app/rpc/[[...rest]]/route.ts] import { RPCHandler } from '@orpc/server/fetch' - -const handler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) async function handleRequest(request: Request) { const { response } = await handler.handle(request, { @@ -49,8 +56,15 @@ The `handler` can be any supported oRPC handler, such as [RPCHandler](/docs/rpc- ```ts [pages/api/rpc/[[...rest]].ts] import { RPCHandler } from '@orpc/server/node' - -const handler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) export const config = { api: { diff --git a/apps/content/docs/adapters/nuxt.md b/apps/content/docs/adapters/nuxt.md index 06ce2750b..54c62b76b 100644 --- a/apps/content/docs/adapters/nuxt.md +++ b/apps/content/docs/adapters/nuxt.md @@ -15,8 +15,15 @@ You set up an oRPC server inside Nuxt using its [Server Routes](https://nuxt.com ```ts [server/routes/rpc/[...].ts] import { RPCHandler } from '@orpc/server/fetch' - -const handler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) export default defineEventHandler(async (event) => { const request = toWebRequest(event) diff --git a/apps/content/docs/adapters/remix.md b/apps/content/docs/adapters/remix.md index 089d2c426..e1a0a8937 100644 --- a/apps/content/docs/adapters/remix.md +++ b/apps/content/docs/adapters/remix.md @@ -11,8 +11,15 @@ description: Use oRPC inside an Remix project ```ts [app/routes/rpc.$.ts] import { RPCHandler } from '@orpc/server/fetch' - -const handler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) export async function loader({ request }: LoaderFunctionArgs) { const { response } = await handler.handle(request, { diff --git a/apps/content/docs/adapters/solid-start.md b/apps/content/docs/adapters/solid-start.md index eb91652ee..d7467bb8f 100644 --- a/apps/content/docs/adapters/solid-start.md +++ b/apps/content/docs/adapters/solid-start.md @@ -14,8 +14,15 @@ description: Use oRPC inside a Solid Start project ```ts [src/routes/rpc/[...rest].ts] import type { APIEvent } from '@solidjs/start/server' import { RPCHandler } from '@orpc/server/fetch' - -const handler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) async function handle({ request }: APIEvent) { const { response } = await handler.handle(request, { diff --git a/apps/content/docs/adapters/svelte-kit.md b/apps/content/docs/adapters/svelte-kit.md index 3d8393c62..556efb939 100644 --- a/apps/content/docs/adapters/svelte-kit.md +++ b/apps/content/docs/adapters/svelte-kit.md @@ -14,8 +14,15 @@ description: Use oRPC inside an Svelte Kit project ```ts [src/routes/rpc/[...rest]/+server.ts] import { error } from '@sveltejs/kit' import { RPCHandler } from '@orpc/server/fetch' - -const handler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) const handle: RequestHandler = async ({ request }) => { const { response } = await handler.handle(request, { diff --git a/apps/content/docs/adapters/tanstack-start.md b/apps/content/docs/adapters/tanstack-start.md index 0ce81a335..5fdc1a125 100644 --- a/apps/content/docs/adapters/tanstack-start.md +++ b/apps/content/docs/adapters/tanstack-start.md @@ -16,8 +16,15 @@ You set up an oRPC server inside TanStack Start using its [Server Routes](https: ```ts [src/routes/api/rpc.$.ts] import { RPCHandler } from '@orpc/server/fetch' import { createFileRoute } from '@tanstack/react-router' +import { onError } from '@orpc/server' -const handler = new RPCHandler(router) +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) async function handle({ request }: { request: Request }) { const { response } = await handler.handle(request, { diff --git a/apps/content/docs/adapters/web-workers.md b/apps/content/docs/adapters/web-workers.md index 0df4002eb..5e574e030 100644 --- a/apps/content/docs/adapters/web-workers.md +++ b/apps/content/docs/adapters/web-workers.md @@ -15,8 +15,15 @@ Configure your Web Worker to handle oRPC requests by upgrading it with a message ```ts import { RPCHandler } from '@orpc/server/message-port' - -const handler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) handler.upgrade(self, { context: {}, // Provide initial context if needed diff --git a/apps/content/docs/adapters/websocket.md b/apps/content/docs/adapters/websocket.md index 18ea3a0e2..8496bd0ea 100644 --- a/apps/content/docs/adapters/websocket.md +++ b/apps/content/docs/adapters/websocket.md @@ -20,8 +20,15 @@ oRPC provides built-in WebSocket support for low-latency, bidirectional RPC. ```ts [Websocket] import { RPCHandler } from '@orpc/server/websocket' - -const handler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) Deno.serve((req) => { if (req.headers.get('upgrade') !== 'websocket') { @@ -41,11 +48,18 @@ Deno.serve((req) => { ```ts [CrossWS] import { createServer } from 'node:http' import { experimental_RPCHandler as RPCHandler } from '@orpc/server/crossws' +import { onError } from '@orpc/server' // any crossws adapter is supported import crossws from 'crossws/adapters/node' -const handler = new RPCHandler(router) +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) const ws = crossws({ hooks: { @@ -74,8 +88,15 @@ server.on('upgrade', (req, socket, head) => { ```ts [WS] import { WebSocketServer } from 'ws' import { RPCHandler } from '@orpc/server/ws' - -const handler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) const wss = new WebSocketServer({ port: 8080 }) @@ -88,8 +109,15 @@ wss.on('connection', (ws) => { ```ts [Bun WebSocket] import { RPCHandler } from '@orpc/server/bun-ws' - -const handler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) Bun.serve({ fetch(req, server) { @@ -114,8 +142,15 @@ Bun.serve({ ```ts [Websocket Hibernation] import { RPCHandler } from '@orpc/server/websocket' - -const handler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) export class ChatRoom extends DurableObject { async fetch(): Promise { diff --git a/apps/content/docs/adapters/worker-threads.md b/apps/content/docs/adapters/worker-threads.md index 5c1c5185e..bcc002f7e 100644 --- a/apps/content/docs/adapters/worker-threads.md +++ b/apps/content/docs/adapters/worker-threads.md @@ -14,8 +14,15 @@ Listen for a `MessagePort` sent from the main thread and upgrade it: ```ts import { parentPort } from 'node:worker_threads' import { RPCHandler } from '@orpc/server/message-port' - -const handler = new RPCHandler(router) +import { onError } from '@orpc/server' + +const handler = new RPCHandler(router, { + interceptors: [ + onError((error) => { + console.error(error) + }), + ], +}) parentPort.on('message', (message) => { if (message instanceof MessagePort) { diff --git a/apps/content/docs/getting-started.md b/apps/content/docs/getting-started.md index 8feada108..97a83b6b1 100644 --- a/apps/content/docs/getting-started.md +++ b/apps/content/docs/getting-started.md @@ -116,9 +116,15 @@ import { router } from './shared/planet' import { createServer } from 'node:http' import { RPCHandler } from '@orpc/server/node' import { CORSPlugin } from '@orpc/server/plugins' +import { onError } from '@orpc/server' const handler = new RPCHandler(router, { - plugins: [new CORSPlugin()] + plugins: [new CORSPlugin()], + interceptors: [ + onError((error) => { + console.error(error) + }), + ], }) const server = createServer(async (req, res) => { diff --git a/apps/content/docs/openapi/getting-started.md b/apps/content/docs/openapi/getting-started.md index 80c0b612d..63010e7b1 100644 --- a/apps/content/docs/openapi/getting-started.md +++ b/apps/content/docs/openapi/getting-started.md @@ -126,9 +126,15 @@ import { router } from './shared/planet' import { createServer } from 'node:http' import { OpenAPIHandler } from '@orpc/openapi/node' import { CORSPlugin } from '@orpc/server/plugins' +import { onError } from '@orpc/server' const handler = new OpenAPIHandler(router, { - plugins: [new CORSPlugin()] + plugins: [new CORSPlugin()], + interceptors: [ + onError((error) => { + console.error(error) + }), + ], }) const server = createServer(async (req, res) => { diff --git a/apps/content/docs/openapi/integrations/trpc.md b/apps/content/docs/openapi/integrations/trpc.md index 6fc6ee5ba..f76d36085 100644 --- a/apps/content/docs/openapi/integrations/trpc.md +++ b/apps/content/docs/openapi/integrations/trpc.md @@ -88,7 +88,9 @@ Learn more about [oRPC OpenAPI Specification Generation](/docs/openapi/openapi-s const handler = new OpenAPIHandler(orpcRouter, { plugins: [new CORSPlugin()], interceptors: [ - onError(error => console.error(error)) + onError((error) => { + console.error(error) + }), ], }) diff --git a/apps/content/docs/openapi/openapi-handler.md b/apps/content/docs/openapi/openapi-handler.md index d9fa8c954..0fba3b254 100644 --- a/apps/content/docs/openapi/openapi-handler.md +++ b/apps/content/docs/openapi/openapi-handler.md @@ -72,7 +72,9 @@ import { onError } from '@orpc/server' const handler = new OpenAPIHandler(router, { plugins: [new CORSPlugin()], interceptors: [ - onError(error => console.error(error)) + onError((error) => { + console.error(error) + }), ], })