Skip to content

docs: recommend use onError in handlers#1148

Merged
dinwwwh merged 1 commit intomainfrom
docs/recommend-use-onError-on-handler
Oct 29, 2025
Merged

docs: recommend use onError in handlers#1148
dinwwwh merged 1 commit intomainfrom
docs/recommend-use-onError-on-handler

Conversation

@dinwwwh
Copy link
Copy Markdown
Member

@dinwwwh dinwwwh commented Oct 29, 2025

Summary by CodeRabbit

  • New Features

    • Added error interceptor support to RPCHandler, enabling centralized error logging across all adapters.
  • Documentation

    • Updated adapter guides and getting-started documentation to demonstrate error handling via interceptors.
    • Included examples for Express, Next.js, Hono, Remix, and other supported frameworks showing how to use error interceptors.

@vercel
Copy link
Copy Markdown

vercel bot commented Oct 29, 2025

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Preview Comments Updated (UTC)
orpc Ready Ready Preview Comment Oct 29, 2025 3:06am

@dosubot dosubot bot added the size:L This PR changes 100-499 lines, ignoring generated files. label Oct 29, 2025
@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Oct 29, 2025

Walkthrough

Documentation across 20+ adapter guides updated to demonstrate error-handling interceptor patterns. Changes consistently replace RPCHandler(router) with RPCHandler(router, { interceptors: [onError(...)] }), importing onError from @orpc/server to illustrate centralized error logging in handler initialization.

Changes

Cohort / File(s) Summary
Adapter Documentation
apps/content/docs/adapters/astro.md, apps/content/docs/adapters/browser.md, apps/content/docs/adapters/electron.md, apps/content/docs/adapters/elysia.md, apps/content/docs/adapters/express.md, apps/content/docs/adapters/h3.md, apps/content/docs/adapters/hono.md, apps/content/docs/adapters/http.md, apps/content/docs/adapters/message-port.md, apps/content/docs/adapters/next.md, apps/content/docs/adapters/nuxt.md, apps/content/docs/adapters/remix.md, apps/content/docs/adapters/solid-start.md, apps/content/docs/adapters/svelte-kit.md, apps/content/docs/adapters/tanstack-start.md, apps/content/docs/adapters/web-workers.md, apps/content/docs/adapters/websocket.md, apps/content/docs/adapters/worker-threads.md
Updated RPCHandler initialization pattern to include interceptors option with onError interceptor for centralized error logging
Getting Started Guides
apps/content/docs/getting-started.md, apps/content/docs/openapi/getting-started.md
Added onError interceptor to handler options while preserving existing plugin configurations
OpenAPI Documentation
apps/content/docs/openapi/integrations/trpc.md, apps/content/docs/openapi/openapi-handler.md
Reformatted onError callback syntax (block-bodied arrow function) for consistency with other examples

Sequence Diagram

sequenceDiagram
    participant Client
    participant Handler as RPCHandler<br/>(w/ interceptors)
    participant onError as onError Interceptor
    participant Router as RPC Router
    participant Log as Console

    Client->>Handler: send RPC request
    Handler->>Router: route request
    
    alt Success Path
        Router-->>Handler: return response
        Handler-->>Client: send response
    else Error Path
        Router--XHandler: throw error
        Handler->>onError: pass error to interceptor
        onError->>Log: console.error(error)
        Log-->>onError: logged
        onError-->>Handler: error processed
        Handler--XClient: send error response
    end
Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

  • Rationale: Highly repetitive pattern applied consistently across documentation files with no complex logic changes. All modifications follow an identical template (add import + update constructor call).
  • Areas for attention:
    • Verify the onError import path is correct across all files (@orpc/server)
    • Confirm interceptors array syntax consistency (especially in files with multiple code blocks)
    • Check that syntax reformatting in OpenAPI docs maintains functional equivalence

Possibly related PRs

  • unnoq/orpc#800: Adds interceptors option to RPCHandler and introduces onError interceptor functionality—the core feature being documented in this PR.
  • unnoq/orpc#710: Implements onError interceptor infrastructure and handler integration patterns that enable the error-handling patterns shown in these documentation examples.
  • unnoq/orpc#526: Refactors interceptor utility types and handler option signatures that define the interceptor API surface being documented across all adapter guides.

Suggested labels

size:M, docs, rpc-handler, interceptors

Poem

🐰✨ Errors caught with gentle care,
onError springs in everywhere,
Through adapters, docs now show the way—
Logs and logs save the day! 🌟📋

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)
Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. You can run @coderabbitai generate docstrings to improve docstring coverage.
✅ Passed checks (2 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check ✅ Passed The PR title "docs: recommend use onError in handlers" accurately reflects the primary objective of the changeset. Across all 24 documentation files modified, the changes consistently add onError interceptor examples to RPCHandler initialization across various adapters (astro, browser, electron, express, h3, hono, next, nuxt, remix, svelte-kit, tanstack-start, websocket, and others). The title is clear, specific, and concise—it directly describes that the documentation is being updated to recommend and demonstrate the use of onError error-handling interceptors in RPC handlers. A developer scanning the commit history would immediately understand that this PR adds documentation guidance about using onError for error handling.
✨ Finishing touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch docs/recommend-use-onError-on-handler

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a55d49f and 3bbc8bb.

📒 Files selected for processing (22)
  • apps/content/docs/adapters/astro.md (1 hunks)
  • apps/content/docs/adapters/browser.md (3 hunks)
  • apps/content/docs/adapters/electron.md (1 hunks)
  • apps/content/docs/adapters/elysia.md (1 hunks)
  • apps/content/docs/adapters/express.md (1 hunks)
  • apps/content/docs/adapters/h3.md (1 hunks)
  • apps/content/docs/adapters/hono.md (1 hunks)
  • apps/content/docs/adapters/http.md (6 hunks)
  • apps/content/docs/adapters/message-port.md (1 hunks)
  • apps/content/docs/adapters/next.md (2 hunks)
  • apps/content/docs/adapters/nuxt.md (1 hunks)
  • apps/content/docs/adapters/remix.md (1 hunks)
  • apps/content/docs/adapters/solid-start.md (1 hunks)
  • apps/content/docs/adapters/svelte-kit.md (1 hunks)
  • apps/content/docs/adapters/tanstack-start.md (1 hunks)
  • apps/content/docs/adapters/web-workers.md (1 hunks)
  • apps/content/docs/adapters/websocket.md (5 hunks)
  • apps/content/docs/adapters/worker-threads.md (1 hunks)
  • apps/content/docs/getting-started.md (1 hunks)
  • apps/content/docs/openapi/getting-started.md (1 hunks)
  • apps/content/docs/openapi/integrations/trpc.md (1 hunks)
  • apps/content/docs/openapi/openapi-handler.md (1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
  • GitHub Check: test
  • GitHub Check: publish-commit
  • GitHub Check: lint
🔇 Additional comments (23)
apps/content/docs/openapi/integrations/trpc.md (2)

91-93: Consistent with best practices across guides.

The onError interceptor pattern is well-demonstrated here. The block-bodied arrow function formatting aligns with the style used across other adapter guides in this PR.


118-130: Good example of advanced error handling.

The second example effectively demonstrates error instanceof checking within the onError interceptor, showing a practical pattern for custom error formatting in tRPC integrations.

apps/content/docs/openapi/openapi-handler.md (1)

70-78: Clear setup example with proper imports.

The documentation clearly shows the import of onError from @orpc/server and demonstrates its integration into the OpenAPIHandler configuration. This serves as a good reference example for the pattern.

apps/content/docs/adapters/svelte-kit.md (1)

17-25: Well-structured handler initialization.

The import and handler setup clearly demonstrate the error interceptor pattern. The spacing and formatting make the code easy to read and understand.

apps/content/docs/adapters/web-workers.md (1)

18-26: Consistent with other adapter patterns.

The onError interceptor setup follows the same pattern as other adapters, providing clear documentation for Web Worker error handling.

apps/content/docs/adapters/tanstack-start.md (1)

19-27: Uniform pattern across TanStack Start adapter.

The error handling setup matches the documentation standard established across other adapters, ensuring consistency for developers switching between different frameworks.

apps/content/docs/adapters/message-port.md (1)

28-36: Clear error handling in message port context.

The example demonstrates the error interceptor pattern within the message port setup, properly contextualizing how onError integrates with handler.upgrade().

apps/content/docs/adapters/hono.md (1)

15-25: Properly positioned in Hono framework context.

The error handler initialization is correctly placed before the middleware registration, maintaining clear flow within the Hono application setup. Pattern is consistent with other adapters.

apps/content/docs/adapters/express.md (1)

20-32: Consistent Express adapter documentation.

The error handler setup follows the established pattern across all adapters, properly positioned before middleware registration.

apps/content/docs/adapters/electron.md (1)

14-24: Pattern aligns with official oRPC best practices.

The onError interceptor import and RPCHandler(router, { interceptors: [onError(...)] }) pattern matches the recommended configuration in oRPC's official documentation. The change is well-integrated and demonstrates error handling best practice clearly.

apps/content/docs/openapi/getting-started.md (1)

129-138: Clean integration of interceptors with existing plugins.

The documentation correctly shows OpenAPIHandler accepting both plugins and interceptors options simultaneously. The onError pattern is properly imported and configured for centralized error logging.

apps/content/docs/getting-started.md (1)

119-128: Excellent placement in primary getting-started guide.

Leading documentation with the onError interceptor pattern teaches best practices early. The pattern matches oRPC's recommended configuration for centralizing error handling in server initialization.

apps/content/docs/adapters/solid-start.md (1)

15-25: Consistent pattern across Solid Start adapter.

The onError interceptor initialization aligns with the framework-agnostic pattern recommended in oRPC documentation.

apps/content/docs/adapters/remix.md (1)

13-22: Consistent implementation for Remix adapter.

The error-handling pattern is properly integrated with Remix's route loader pattern.

apps/content/docs/adapters/nuxt.md (1)

17-26: Consistent pattern for Nuxt adapter.

The onError interceptor is properly wired into the RPCHandler initialization for Nuxt's server routes.

apps/content/docs/adapters/h3.md (1)

14-25: Consistent H3 adapter implementation.

The interceptor pattern is properly applied to the H3 framework integration.

apps/content/docs/adapters/astro.md (1)

15-24: Consistent Astro adapter implementation.

The onError interceptor pattern is correctly applied and consistent across all adapter documentation.

apps/content/docs/adapters/elysia.md (1)

14-23: Solid example demonstrating centralized error handling.

The pattern is clear and the onError interceptor is properly wired into RPCHandler initialization. The example demonstrates a practical approach to error logging.

apps/content/docs/adapters/worker-threads.md (1)

17-25: Consistent with other adapter examples.

The pattern matches the Elysia adapter and correctly uses @orpc/server/message-port module path for Worker Threads communication.

apps/content/docs/adapters/browser.md (1)

22-30: Exemplary consistency across multiple browser scenarios.

All three browser communication patterns (extension scripts, window-to-window, relay) demonstrate the onError interceptor consistently. This reinforces the recommended practice across different browser use cases.

Also applies to: 63-71, 140-148

apps/content/docs/adapters/next.md (1)

22-30: Correct pattern for both Next.js routing approaches.

App Router and Pages Router examples properly demonstrate onError interceptor with the appropriate module paths (@orpc/server/fetch vs @orpc/server/node).

Also applies to: 59-67

apps/content/docs/adapters/http.md (1)

25-35: Exemplary coverage demonstrating pattern across all HTTP adapters.

Six diverse adapters (node, bun, cloudflare, deno, fastify, aws-lambda) consistently implement the onError interceptor pattern. Each uses the correct module path for its runtime, clearly establishing this as a universal best practice.

Also applies to: 58-68, 90-100, 122-132, 152-159, 186-193

apps/content/docs/adapters/websocket.md (1)

23-31: Consistent pattern across all WebSocket implementations.

Five WebSocket adapters (Websocket, CrossWS, WS, Bun, Hibernation) consistently demonstrate onError interception. The pattern applies equally to bidirectional protocols, reinforcing that centralized error handling via interceptors is a universal recommendation.

Also applies to: 51-62, 91-99, 112-120, 145-153


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@gemini-code-assist
Copy link
Copy Markdown
Contributor

Summary of Changes

Hello @unnoq, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly improves the oRPC documentation by integrating a recommended error handling pattern across all handler examples. By explicitly showcasing the onError interceptor in RPCHandler and OpenAPIHandler configurations, the changes guide developers towards implementing more resilient and observable RPC services. This update ensures that errors are consistently logged, aiding in debugging and maintaining application stability across various server environments and frameworks.

Highlights

  • Standardized Error Handling: All RPCHandler and OpenAPIHandler examples across the documentation now explicitly include the onError interceptor for consistent error logging.
  • Improved Documentation Clarity: The updated code snippets provide clearer guidance on how to implement robust error handling within oRPC applications, regardless of the chosen adapter.
  • Elysia Adapter Update: The Elysia adapter example was updated to use RPCHandler instead of OpenAPIHandler, aligning it with typical RPC handler usage and integrating the new error handling recommendation.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request systematically updates documentation examples across multiple adapter guides to include the onError interceptor. This is a great change that promotes best practices for error handling by showing developers how to log errors from their handlers. The implementation is consistent across all modified files, including the change from OpenAPIHandler to RPCHandler in the Elysia adapter guide for better consistency with other examples. The code is correct and improves the quality of the documentation. I have no suggestions for improvement.

@codecov
Copy link
Copy Markdown

codecov bot commented Oct 29, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@pkg-pr-new
Copy link
Copy Markdown

pkg-pr-new bot commented Oct 29, 2025

More templates

@orpc/arktype

npm i https://pkg.pr.new/@orpc/arktype@1148

@orpc/client

npm i https://pkg.pr.new/@orpc/client@1148

@orpc/contract

npm i https://pkg.pr.new/@orpc/contract@1148

@orpc/experimental-durable-iterator

npm i https://pkg.pr.new/@orpc/experimental-durable-iterator@1148

@orpc/hey-api

npm i https://pkg.pr.new/@orpc/hey-api@1148

@orpc/interop

npm i https://pkg.pr.new/@orpc/interop@1148

@orpc/json-schema

npm i https://pkg.pr.new/@orpc/json-schema@1148

@orpc/nest

npm i https://pkg.pr.new/@orpc/nest@1148

@orpc/openapi

npm i https://pkg.pr.new/@orpc/openapi@1148

@orpc/openapi-client

npm i https://pkg.pr.new/@orpc/openapi-client@1148

@orpc/otel

npm i https://pkg.pr.new/@orpc/otel@1148

@orpc/experimental-publisher

npm i https://pkg.pr.new/@orpc/experimental-publisher@1148

@orpc/react

npm i https://pkg.pr.new/@orpc/react@1148

@orpc/react-query

npm i https://pkg.pr.new/@orpc/react-query@1148

@orpc/experimental-react-swr

npm i https://pkg.pr.new/@orpc/experimental-react-swr@1148

@orpc/server

npm i https://pkg.pr.new/@orpc/server@1148

@orpc/shared

npm i https://pkg.pr.new/@orpc/shared@1148

@orpc/solid-query

npm i https://pkg.pr.new/@orpc/solid-query@1148

@orpc/standard-server

npm i https://pkg.pr.new/@orpc/standard-server@1148

@orpc/standard-server-aws-lambda

npm i https://pkg.pr.new/@orpc/standard-server-aws-lambda@1148

@orpc/standard-server-fastify

npm i https://pkg.pr.new/@orpc/standard-server-fastify@1148

@orpc/standard-server-fetch

npm i https://pkg.pr.new/@orpc/standard-server-fetch@1148

@orpc/standard-server-node

npm i https://pkg.pr.new/@orpc/standard-server-node@1148

@orpc/standard-server-peer

npm i https://pkg.pr.new/@orpc/standard-server-peer@1148

@orpc/svelte-query

npm i https://pkg.pr.new/@orpc/svelte-query@1148

@orpc/tanstack-query

npm i https://pkg.pr.new/@orpc/tanstack-query@1148

@orpc/trpc

npm i https://pkg.pr.new/@orpc/trpc@1148

@orpc/valibot

npm i https://pkg.pr.new/@orpc/valibot@1148

@orpc/vue-colada

npm i https://pkg.pr.new/@orpc/vue-colada@1148

@orpc/vue-query

npm i https://pkg.pr.new/@orpc/vue-query@1148

@orpc/zod

npm i https://pkg.pr.new/@orpc/zod@1148

commit: 3bbc8bb

@dinwwwh dinwwwh merged commit 440b07e into main Oct 29, 2025
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:L This PR changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant