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.
Hono is 3.5 times faster than Express.
Express:
$ bombardier -d 10s --fasthttp http://localhost:3000/
Statistics Avg Stdev Max
Reqs/sec 16438.94 1603.39 19155.47
Latency 7.60ms 7.51ms 559.89ms
HTTP codes:
1xx - 0, 2xx - 164494, 3xx - 0, 4xx - 0, 5xx - 0
others - 0
Throughput: 4.55MB/s
Hono + @hono/node-server
:
$ bombardier -d 10s --fasthttp http://localhost:3000/
Statistics Avg Stdev Max
Reqs/sec 58296.56 5512.74 74403.56
Latency 2.14ms 1.46ms 190.92ms
HTTP codes:
1xx - 0, 2xx - 583059, 3xx - 0, 4xx - 0, 5xx - 0
others - 0
Throughput: 12.56MB/s
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.
You can install from npm registry with npm
command:
npm install @hono/node-server
Or use yarn
:
yarn add @hono/node-server
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.
import { serve } from '@hono/node-server'
import { Hono } from 'hono'
const app = new Hono()
app.get('/', (c) => c.text('Hono meets Node.js'))
serve(app, (info) => {
console.log(`Listening on http://localhost:${info.port}`) // Listening on http://localhost:3000
})
For example, run it using ts-node
. Then an HTTP server will be launched. The default port is 3000
.
ts-node ./index.ts
Open http://localhost:3000
with your browser.
serve({
fetch: app.fetch,
port: 8787, // Port number, default is 3000
})
import { createServer } from 'node:https'
import fs from 'node:fs'
//...
serve({
fetch: app.fetch,
createServer: createServer,
serverOptions: {
key: fs.readFileSync('test/fixtures/keys/agent1-key.pem'),
cert: fs.readFileSync('test/fixtures/keys/agent1-cert.pem'),
},
})
Most built-in middleware also works with Node.js. Read the documentation and use the Middleware of your liking.
import { serve } from '@hono/node-server'
import { Hono } from 'hono'
import { prettyJSON } from 'hono/pretty-json'
const app = new Hono()
app.get('*', prettyJSON())
app.get('/', (c) => c.json({ 'Hono meets': 'Node.js' }))
serve(app)
Use Serve Static Middleware that has been created for Node.js.
import { serveStatic } from '@hono/node-server/serve-static'
//...
app.use('/static/*', serveStatic({ root: './' }))
Note that root
must be relative to the current working directory - absolute paths are not supported.
If you want to serve files in ./.foojs
with the request path /__foo/*
, you can write like the following.
app.use(
'/__foo/*',
serveStatic({
root: './.foojs/',
rewriteRequestPath: (path: string) => path.replace(/^\/__foo/, ''),
})
)
The onNotFound
is useful for debugging. You can write a handle for when a file is not found.
app.use(
'/static/*',
serveStatic({
root: './non-existent-dir',
onNotFound: (path, c) => {
console.log(`${path} is not found, request to ${c.req.path}`)
},
})
)
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.
import { serve } from '@hono/node-server'
import type { HttpBindings } from '@hono/node-server'
import { Hono } from 'hono'
const app = new Hono<{ Bindings: HttpBindings }>()
app.get('/', (c) => {
return c.json({
remoteAddress: c.env.incoming.socket.remoteAddress,
})
})
serve(app)
The APIs that you can get from c.env
are as follows.
type HttpBindings = {
incoming: IncomingMessage
outgoing: ServerResponse
}
type Http2Bindings = {
incoming: Http2ServerRequest
outgoing: Http2ServerResponse
}
- Hono - https://hono.dev
- Hono GitHub repository - https://github.com/honojs/hono
Yusuke Wada https://github.com/yusukebe
MIT