Cloudflare Workers fetch export
For Cloudflare Workers, export an object with a fetch method that accepts request, env, and ctx parameters, passing them to app.fetch(). Alternatively, export the app instance directly as the default export.
runtimes
15 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Node.js runtime support and version requirements
Hono runs on Node.js versions 18.x and above. Specific minimum versions are: 18.x requires 18.14.1 or higher, 19.x requires 19.7.0 or higher, and 20.x requires 20.0.0 or higher. It is recommended to use the latest version of each major release.
Node.js adapter for Hono
Hono runs on Node.js through the Node.js Adapter available at https://github.com/honojs/node-server. Hono was not originally designed for Node.js but the adapter enables Node.js compatibility.
Create Hono Node.js project setup
To start a Hono project on Node.js, use the 'create hono' command and select the 'nodejs' template. Commands include: npm create hono@latest my-app, yarn create hono my-app, pnpm create hono my-app, bun create hono@latest my-app, or deno init --npm hono my-app.
Basic Hello World example for Node.js
Here is a minimal Hono application for Node.js: ```ts import { serve } from '@hono/node-server' import { Hono } from 'hono' const app = new Hono() app.get('/', (c) => c.text('Hello Node.js!')) serve(app) ```
Graceful server shutdown on Node.js
To implement graceful shutdown on Node.js, capture the server returned from serve() and listen to SIGINT and SIGTERM signals: ```ts const server = serve(app) // graceful shutdown process.on('SIGINT', () => { server.close() process.exit(0) }) process.on('SIGTERM', () => { server.close((err) => { if (err) { console.error(err) process.exit(1) } process.exit(0) }) }) ``` On Node.js, serve() wraps the node:http module and returns the underlying server instance, so closing it is the developer's responsibility. Bun and Deno handle this automatically.
Change port number in Node.js
Specify the port number using the port option passed to serve(): ```ts serve({ fetch: app.fetch, port: 8787, }) ```
WebSocket support on Node.js
WebSocket support is built into @hono/node-server. Install the ws package and @types/ws for TypeScript. Create a WebSocketServer with { noServer: true } and pass it to serve() with the websocket option: ```ts import { serve, upgradeWebSocket } from '@hono/node-server' import { Hono } from 'hono' import { WebSocketServer } from 'ws' const app = new Hono() app.get( '/ws', upgradeWebSocket(() => ({ onMessage(event, ws) { ws.send(event.data) }, })) ) const wss = new WebSocketServer({ noServer: true }) serve({ fetch: app.fetch, websocket: { server: wss }, }) ``` Note: @hono/node-ws is deprecated.
Access raw Node.js APIs in handlers
Access Node.js APIs through c.env.incoming (the Node.js IncomingMessage) and c.env.outgoing (the Node.js ServerResponse). Type the context with HttpBindings or Http2Bindings from @hono/node-server: ```ts import { Hono } from 'hono' import { serve, type HttpBindings } from '@hono/node-server' // or `Http2Bindings` if you use HTTP2 type Bindings = HttpBindings & { /* ... */ } const app = new Hono<{ Bindings: Bindings }>() app.get('/', (c) => { return c.json({ remoteAddress: c.env.incoming.socket.remoteAddress, }) }) serve(app) ```
serveStatic middleware for Node.js
Use serveStatic from @hono/node-server/serve-static to serve static files from the local file system. The root option resolves paths relative to process.cwd(), so behavior depends on where the Node.js process is started from, not where the source file is located. For reliable path resolution, use import.meta.url: ```ts import { fileURLToPath } from 'node:url' import { serveStatic } from '@hono/node-server/serve-static' app.use( '/static/*', serveStatic({ root: fileURLToPath(new URL('./', import.meta.url)) }) ) ```
serveStatic options for serving individual files
To serve a single file like favicon.ico in the directory root, use the path option: ```ts app.use('/favicon.ico', serveStatic({ path: './favicon.ico' })) ``` To serve files from a specific directory (e.g., ./static/hello.txt when requesting /hello.txt), use: ```ts app.use('*', serveStatic({ root: './static' })) ```
serveStatic rewriteRequestPath option
Use the rewriteRequestPath option to map request paths to different file system paths. For example, to map http://localhost:3000/static/* to ./statics: ```ts app.get( '/static/*', serveStatic({ root: './', rewriteRequestPath: (path) => path.replace(/^\/static/, '/statics'), }) ) ```
HTTP/2 support on Node.js
Hono can run on Node.js HTTP/2 servers. For unencrypted HTTP/2, use createServer from node:http2: ```ts import { createServer } from 'node:http2' const server = serve({ fetch: app.fetch, createServer, }) ``` For encrypted HTTP/2 with TLS, use createSecureServer with serverOptions containing key and cert: ```ts import { createSecureServer } from 'node:http2' import { readFileSync } from 'node:fs' const server = serve({ fetch: app.fetch, createServer: createSecureServer, serverOptions: { key: readFileSync('localhost-privkey.pem'), cert: readFileSync('localhost-cert.pem'), }, }) ```
Dockerfile example for Node.js deployment
Here is an example multi-stage Dockerfile for deploying a Hono application on Node.js: ```Dockerfile FROM node:22-alpine AS base FROM base AS builder RUN apk add --no-cache gcompat WORKDIR /app COPY package*json tsconfig.json src ./ RUN npm ci && \ npm run build && \ npm prune --production FROM base AS runner WORKDIR /app RUN addgroup --system --gid 1001 nodejs RUN adduser --system --uid 1001 hono COPY --from=builder --chown=hono:nodejs /app/node_modules /app/node_modules COPY --from=builder --chown=hono:nodejs /app/dist /app/dist COPY --from=builder --chown=hono:nodejs /app/package.json /app/package.json USER hono EXPOSE 3000 CMD ["node", "/app/dist/index.js"] ```
Build and deploy Hono on Node.js
To build a Hono application for Node.js, use npm run build, yarn run build, pnpm run build, or bun run build. Apps with a front-end framework may need Hono's Vite plugins available at https://github.com/honojs/vite-plugins.