feat(nest): add Hono framework support (#1299)

Mnigos · web-flow · commit 90a4d223898f · 2026-05-04T07:49:50.000+07:00
## Summary

Adds Hono-based HTTP adapter support to `@orpc/nest` so `@Implement`
routes can run in Nest applications backed by a Hono adapter.

## Changes

- Added Fetch request/response handling for Hono adapter contexts via
`@orpc/standard-server-fetch`.
- Detects Hono response contexts by their Fetch response factory and
returns a Hono-native `Response` with `newResponse(...)`.
- Adds `OPTIONS` route decorator support for implemented contract
routes.
- Adds compatibility coverage using `@mnigos/platform-hono@^0.1.3`,
including request body/query/header parsing, route params, response
headers, and error responses.
- Documents Hono-based adapter usage with `@mnigos/platform-hono` as an
example.


&lt;!-- This is an auto-generated comment: release notes by coderabbit.ai
--&gt;
## Summary by CodeRabbit

* **New Features**
* Added runtime support for Hono adapters so the package can run on
Hono-powered servers alongside existing environments.
* Interceptor now routes and converts requests/responses correctly
across supported adapters.

* **Documentation**
* New guide section on using the Hono adapter with recommended
configuration notes.

* **Tests**
* Added compatibility tests verifying handlers and routes work when the
app runs with the Hono adapter.
&lt;!-- end of auto-generated comment: release notes by coderabbit.ai --&gt;
diff --git a/apps/content/docs/openapi/integrations/implement-contract-in-nest.md b/apps/content/docs/openapi/integrations/implement-contract-in-nest.md
@@ -214,6 +214,37 @@ async function bootstrap() {
 oRPC will use NestJS parsed body when it's available, and only use the oRPC parser if the body is not parsed by NestJS.
 :::
 
+## Hono Adapter
+
+`@orpc/nest` supports NestJS applications that use Hono-based HTTP adapters.
+
+For example, install [`@mnigos/platform-hono`](https://www.npmjs.com/package/@mnigos/platform-hono)
+and its Hono peer dependencies:
+
+```sh
+pnpm add @mnigos/platform-hono @hono/node-server hono
+```
+
+Then pass the adapter to `NestFactory.create`:
+
+```ts
+import { HonoAdapter } from '@mnigos/platform-hono'
+import { NestFactory } from '@nestjs/core'
+import { AppModule } from './app.module'
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule, new HonoAdapter(), {
+    bodyParser: false,
+  })
+
+  await app.listen(process.env.PORT ?? 3000)
+}
+```
+
+`@Implement` routes continue to use the same contract paths and route
+parameters. Internally, oRPC reads the Hono `Request` and returns a Hono-native
+`Response` through the adapter response context.
+
 ## Configuration
 
 Configure the `@orpc/nest` module by importing `ORPCModule` in your NestJS application:
diff --git a/packages/nest/package.json b/packages/nest/package.json
@@ -57,10 +57,13 @@
     "@orpc/shared": "workspace:*",
     "@orpc/standard-server": "workspace:*",
     "@orpc/standard-server-fastify": "workspace:*",
+    "@orpc/standard-server-fetch": "workspace:*",
     "@orpc/standard-server-node": "workspace:*"
   },
   "devDependencies": {
     "@fastify/cookie": "^11.0.2",
+    "@hono/node-server": "^1.19.11",
+    "@mnigos/platform-hono": "^0.1.3",
     "@nestjs/common": "^11.1.16",
     "@nestjs/core": "^11.1.16",
     "@nestjs/platform-express": "^11.1.16",
@@ -70,6 +73,7 @@
     "@types/express": "^5.0.6",
     "express": "^5.2.1",
     "fastify": "^5.8.3",
+    "hono": "^4.10.7",
     "rxjs": "^7.8.2",
     "supertest": "^7.1.4",
     "zod": "^4.3.6"
diff --git a/packages/nest/src/implement.test.ts b/packages/nest/src/implement.test.ts
@@ -2,6 +2,7 @@ import type { NodeHttpRequest } from '@orpc/standard-server-node'
 import type { Request } from 'express'
 import type { FastifyReply } from 'fastify'
 import FastifyCookie from '@fastify/cookie'
+import { HonoAdapter } from '@mnigos/platform-hono'
 import { Controller, Req, Res } from '@nestjs/common'
 import { REQUEST } from '@nestjs/core'
 import { FastifyAdapter } from '@nestjs/platform-fastify'
@@ -671,6 +672,88 @@ describe('@Implement', async () => {
   })
 
   describe('compatibility', () => {
+    it('works with @mnigos/platform-hono', async () => {
+      @Controller()
+      class HonoController {
+        @Implement(contract.ping)
+        ping() {
+          return implement(contract.ping).handler(ping_handler)
+        }
+
+        @Implement(contract.pong)
+        pong() {
+          return implement(contract.pong).handler(pong_handler)
+        }
+
+        @Implement(contract.nested.peng)
+        peng() {
+          return implement(contract.nested.peng).handler(peng_handler)
+        }
+      }
+
+      const moduleRef = await Test.createTestingModule({
+        controllers: [HonoController],
+      }).compile()
+
+      const adapter = new HonoAdapter()
+      const app = moduleRef.createNestApplication(adapter, { bodyParser: false })
+      await app.init()
+      await app.listen(0)
+
+      const httpServer = app.getHttpServer()
+
+      try {
+        const pingRes = await supertest(httpServer)
+          .post('/ping?param=value&param2[]=value2&param2[]=value3')
+          .set('x-custom', 'value')
+          .send({ hello: 'world' })
+
+        expect(pingRes.statusCode).toEqual(200)
+        expect(pingRes.body).toEqual('pong')
+        expect(pingRes.headers).toEqual(expect.objectContaining({ 'x-ping': 'pong' }))
+
+        expect(ping_handler).toHaveBeenCalledWith(expect.objectContaining({
+          input: {
+            headers: expect.objectContaining({
+              'x-custom': 'value',
+            }),
+            body: { hello: 'world' },
+            params: {},
+            query: {
+              param: 'value',
+              param2: ['value2', 'value3'],
+            },
+          },
+        }))
+
+        const pongRes = await supertest(httpServer).get('/pong/world')
+
+        expect(pongRes.statusCode).toEqual(408)
+        expect(pongRes.body).toEqual(expect.objectContaining({
+          code: 'TEST',
+          data: 'pong world',
+        }))
+        expect(pong_handler).toHaveBeenCalledWith(expect.objectContaining({
+          input: {
+            name: 'world',
+          },
+        }))
+
+        const pengRes = await supertest(httpServer).delete('/world/who%3F')
+
+        expect(pengRes.statusCode).toEqual(202)
+        expect(pengRes.body).toEqual('peng world/who?')
+        expect(peng_handler).toHaveBeenCalledWith(expect.objectContaining({
+          input: {
+            path: 'world/who?',
+          },
+        }))
+      }
+      finally {
+        await app.close()
+      }
+    })
+
     it('work with fastify/cookie', async () => {
       @Controller()
       class FastifyController {
diff --git a/packages/nest/src/implement.ts b/packages/nest/src/implement.ts
@@ -7,26 +7,35 @@ import type { Request, Response } from 'express'
 import type { FastifyReply, FastifyRequest } from 'fastify'
 import type { Observable } from 'rxjs'
 import type { ORPCGlobalContext, ORPCModuleConfig } from './module'
-import { applyDecorators, Delete, Get, Head, HttpCode, Inject, Injectable, Optional, Patch, Post, Put, UseInterceptors } from '@nestjs/common'
+import { applyDecorators, Delete, Get, Head, HttpCode, Inject, Injectable, Optional, Options, Patch, Post, Put, UseInterceptors } from '@nestjs/common'
 import { fallbackContractConfig, isContractProcedure } from '@orpc/contract'
 import { StandardBracketNotationSerializer, StandardOpenAPIJsonSerializer, StandardOpenAPISerializer } from '@orpc/openapi-client/standard'
 import { StandardOpenAPICodec } from '@orpc/openapi/standard'
 import { getRouter, isProcedure, unlazy } from '@orpc/server'
 import { StandardHandler } from '@orpc/server/standard'
 import { get, intercept, toArray } from '@orpc/shared'
 import * as StandardServerFastify from '@orpc/standard-server-fastify'
+import * as StandardServerFetch from '@orpc/standard-server-fetch'
 import * as StandardServerNode from '@orpc/standard-server-node'
 import { mergeMap } from 'rxjs'
 import { ORPC_MODULE_CONFIG_SYMBOL } from './module'
 import { toNestPattern } from './utils'
 
+interface HonoContext {
+  req: { raw: globalThis.Request, params?: NestParams }
+  res?: globalThis.Response
+  finalized: boolean
+  newResponse: (...args: any[]) => globalThis.Response
+}
+
 const MethodDecoratorMap = {
   HEAD: Head,
   GET: Get,
   POST: Post,
   PUT: Put,
   PATCH: Patch,
   DELETE: Delete,
+  OPTIONS: Options,
 }
 
 /**
@@ -122,16 +131,26 @@ export class ImplementInterceptor implements NestInterceptor {
           `)
         }
 
-        const req: Request | FastifyRequest = ctx.switchToHttp().getRequest()
-        const res: Response | FastifyReply = ctx.switchToHttp().getResponse()
+        const req: Request | FastifyRequest | HonoContext['req'] = ctx.switchToHttp().getRequest()
+        const res: Response | FastifyReply | HonoContext = ctx.switchToHttp().getResponse()
 
-        const standardRequest = 'raw' in req
-          ? StandardServerFastify.toStandardLazyRequest(req, res as FastifyReply)
-          : StandardServerNode.toStandardLazyRequest(req, res as Response)
+        // Detect a Hono adapter response context by its Fetch response factory.
+        const isHono = 'finalized' in res && typeof (res as HonoContext).newResponse === 'function'
+        const isFastify = 'raw' in req && !isHono
+
+        const standardRequest = (() => {
+          if (isHono) {
+            return StandardServerFetch.toStandardLazyRequest((req as HonoContext['req']).raw)
+          }
+          if (isFastify) {
+            return StandardServerFastify.toStandardLazyRequest(req as FastifyRequest, res as FastifyReply)
+          }
+          return StandardServerNode.toStandardLazyRequest(req as Request, res as Response)
+        })()
 
         const handler = new StandardHandler(procedure, {
           init: () => {},
-          match: () => Promise.resolve({ path: toArray(this.config.path), procedure, params: flattenParams(req.params as NestParams) }),
+          match: () => Promise.resolve({ path: toArray(this.config.path), procedure, params: flattenParams(req.params as NestParams | undefined) }),
         }, this.codec, {
           // Since plugins can modify options directly, so we need to clone to avoid affecting other handlers/requests
           // TODO: improve plugins system to avoid this cloning
@@ -148,11 +167,15 @@ export class ImplementInterceptor implements NestInterceptor {
             toArray(this.config.sendResponseInterceptors),
             { request: req, response: res, standardResponse: result.response },
             async ({ response, standardResponse }) => {
-              if ('raw' in response) {
-                await StandardServerFastify.sendStandardResponse(response, standardResponse, this.config)
+              if (isHono) {
+                const fetchResponse = StandardServerFetch.toFetchResponse(standardResponse, this.config)
+                return (response as HonoContext).newResponse(fetchResponse.body, fetchResponse)
+              }
+              else if (isFastify) {
+                await StandardServerFastify.sendStandardResponse(response as FastifyReply, standardResponse, this.config)
               }
               else {
-                await StandardServerNode.sendStandardResponse(response, standardResponse, this.config)
+                await StandardServerNode.sendStandardResponse(response as Response, standardResponse, this.config)
               }
             },
           )
@@ -162,10 +185,10 @@ export class ImplementInterceptor implements NestInterceptor {
   }
 }
 
-function flattenParams(params: NestParams): StandardParams {
+function flattenParams(params: NestParams | undefined): StandardParams {
   const flatten: StandardParams = {}
 
-  for (const [key, value] of Object.entries(params)) {
+  for (const [key, value] of Object.entries(params ?? {})) {
     if (Array.isArray(value)) {
       flatten[key] = value.join('/')
     }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
