Node.js Adapter for Hono

This adapter @hono/node-server allows you to run your Hono application on Node.js. Initially, Hono wasn't designed for Node.js, but with this adapter, you can now use Hono on Node.js. It utilizes web standard APIs implemented in Node.js version 18 or higher.

Benchmarks

Hono is 3.5 times faster than Express.

Express:

1$ bombardier -d 10s --fasthttp http://localhost:3000/
2
3Statistics        Avg      Stdev        Max
4  Reqs/sec     16438.94    1603.39   19155.47
5  Latency        7.60ms     7.51ms   559.89ms
6  HTTP codes:
7    1xx - 0, 2xx - 164494, 3xx - 0, 4xx - 0, 5xx - 0
8    others - 0
9  Throughput:     4.55MB/s

Hono + @hono/node-server:

1$ bombardier -d 10s --fasthttp http://localhost:3000/
2
3Statistics        Avg      Stdev        Max
4  Reqs/sec     58296.56    5512.74   74403.56
5  Latency        2.14ms     1.46ms   190.92ms
6  HTTP codes:
7    1xx - 0, 2xx - 583059, 3xx - 0, 4xx - 0, 5xx - 0
8    others - 0
9  Throughput:    12.56MB/s

Requirements

It works on Node.js versions greater than 18.x. The specific required Node.js versions are as follows:

• 18.x => 18.14.1+
• 19.x => 19.7.0+
• 20.x => 20.0.0+

Essentially, you can simply use the latest version of each major release.

Installation

You can install it from the npm registry with npm command:

1npm install @hono/node-server

Or use yarn:

1yarn add @hono/node-server

Usage

Just import @hono/node-server at the top and write the code as usual. The same code that runs on Cloudflare Workers, Deno, and Bun will work.

1import { serve } from '@hono/node-server'
2import { Hono } from 'hono'
3
4const app = new Hono()
5app.get('/', (c) => c.text('Hono meets Node.js'))
6
7serve(app, (info) => {
8  console.log(`Listening on http://localhost:${info.port}`) // Listening on http://localhost:3000
9})

For example, run it using ts-node. Then an HTTP server will be launched. The default port is 3000.

1ts-node ./index.ts

Open http://localhost:3000 with your browser.

Options

port

1serve({
2  fetch: app.fetch,
3  port: 8787, // Port number, default is 3000
4})

createServer

1import { createServer } from 'node:https'
2import fs from 'node:fs'
3
4//...
5
6serve({
7  fetch: app.fetch,
8  createServer: createServer,
9  serverOptions: {
10    key: fs.readFileSync('test/fixtures/keys/agent1-key.pem'),
11    cert: fs.readFileSync('test/fixtures/keys/agent1-cert.pem'),
12  },
13})

overrideGlobalObjects

The default value is true. The Node.js Adapter rewrites the global Request/Response and uses a lightweight Request/Response to improve performance. If you don't want to do that, set false.

1serve({
2  fetch: app.fetch,
3  overrideGlobalObjects: false,
4})

autoCleanupIncoming

The default value is true. The Node.js Adapter automatically cleans up (explicitly call destroy() method) if application is not finished to consume the incoming request. If you don't want to do that, set false. If the application accepts connections from arbitrary clients, this cleanup must be done otherwise incomplete requests from clients may cause the application to stop responding. If your application only accepts connections from trusted clients, such as in a reverse proxy environment and there is no process that returns a response without reading the body of the POST request all the way through, you can improve performance by setting it to false.

1serve({
2  fetch: app.fetch,
3  autoCleanupIncoming: false,
4})

Middleware

Most built-in middleware also works with Node.js. Read the documentation and use the Middleware of your liking.

1import { serve } from '@hono/node-server'
2import { Hono } from 'hono'
3import { prettyJSON } from 'hono/pretty-json'
4
5const app = new Hono()
6
7app.get('*', prettyJSON())
8app.get('/', (c) => c.json({ 'Hono meets': 'Node.js' }))
9
10serve(app)

Serve Static Middleware

Use Serve Static Middleware that has been created for Node.js.

1import { serveStatic } from '@hono/node-server/serve-static'
2
3//...
4
5app.use('/static/*', serveStatic({ root: './' }))

Note that root must be relative to the current working directory from which the app was started. Absolute paths are not supported.

This can cause confusion when running your application locally.

Imagine your project structure is:

my-hono-project/
  src/
    index.ts
  static/
    index.html

Typically, you would run your app from the project's root directory (my-hono-project), so you would need the following code to serve the static folder:

1app.use('/static/*', serveStatic({ root: './static' }))

Notice that root here is not relative to src/index.ts, rather to my-hono-project.

Options

rewriteRequestPath

If you want to serve files in ./.foojs with the request path /__foo/*, you can write like the following.

1app.use(
2  '/__foo/*',
3  serveStatic({
4    root: './.foojs/',
5    rewriteRequestPath: (path: string) => path.replace(/^\/__foo/, ''),
6  })
7)

onFound

You can specify handling when the requested file is found with onFound.

1app.use(
2  '/static/*',
3  serveStatic({
4    // ...
5    onFound: (_path, c) => {
6      c.header('Cache-Control', `public, immutable, max-age=31536000`)
7    },
8  })
9)

onNotFound

The onNotFound is useful for debugging. You can write a handle for when a file is not found.

1app.use(
2  '/static/*',
3  serveStatic({
4    root: './non-existent-dir',
5    onNotFound: (path, c) => {
6      console.log(`${path} is not found, request to ${c.req.path}`)
7    },
8  })
9)

precompressed

The precompressed option checks if files with extensions like .br or .gz are available and serves them based on the Accept-Encoding header. It prioritizes Brotli, then Zstd, and Gzip. If none are available, it serves the original file.

1app.use(
2  '/static/*',
3  serveStatic({
4    precompressed: true,
5  })
6)

ConnInfo Helper

You can use the ConnInfo Helper by importing getConnInfo from @hono/node-server/conninfo.

1import { getConnInfo } from '@hono/node-server/conninfo'
2
3app.get('/', (c) => {
4  const info = getConnInfo(c) // info is `ConnInfo`
5  return c.text(`Your remote address is ${info.remote.address}`)
6})

Accessing Node.js API

You can access the Node.js API from c.env in Node.js. For example, if you want to specify a type, you can write the following.

1import { serve } from '@hono/node-server'
2import type { HttpBindings } from '@hono/node-server'
3import { Hono } from 'hono'
4
5const app = new Hono<{ Bindings: HttpBindings }>()
6
7app.get('/', (c) => {
8  return c.json({
9    remoteAddress: c.env.incoming.socket.remoteAddress,
10  })
11})
12
13serve(app)

The APIs that you can get from c.env are as follows.

1type HttpBindings = {
2  incoming: IncomingMessage
3  outgoing: ServerResponse
4}
5
6type Http2Bindings = {
7  incoming: Http2ServerRequest
8  outgoing: Http2ServerResponse
9}

Direct response from Node.js API

You can directly respond to the client from the Node.js API. In that case, the response from Hono should be ignored, so return RESPONSE_ALREADY_SENT.

[!NOTE] This feature can be used when migrating existing Node.js applications to Hono, but we recommend using Hono's API for new applications.

1import { serve } from '@hono/node-server'
2import type { HttpBindings } from '@hono/node-server'
3import { RESPONSE_ALREADY_SENT } from '@hono/node-server/utils/response'
4import { Hono } from 'hono'
5
6const app = new Hono<{ Bindings: HttpBindings }>()
7
8app.get('/', (c) => {
9  const { outgoing } = c.env
10  outgoing.writeHead(200, { 'Content-Type': 'text/plain' })
11  outgoing.end('Hello World\n')
12
13  return RESPONSE_ALREADY_SENT
14})
15
16serve(app)

Related projects

• Hono - https://hono.dev
• Hono GitHub repository - https://github.com/honojs/hono

Author

Yusuke Wada https://github.com/yusukebe

License

MIT