Node.js
Node.js is an open-source, cross-platform JavaScript runtime environment.
Hono was not designed for Node.js at first. But with a Node.js Adapter it can run on Node.js as well.
INFO
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.
1. Setup
A starter for Node.js is available. Start your project with "create-hono" command. Select nodejs
template for this example.
npm create hono@latest my-app
yarn create hono my-app
pnpm create hono my-app
bunx create-hono my-app
deno run -A npm:create-hono my-app
Move to my-app
and install the dependencies.
cd my-app
npm i
cd my-app
yarn
cd my-app
pnpm i
cd my-app
bun i
2. Hello World
Edit src/index.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)
3. Run
Run the development server locally. Then, access http://localhost:3000
in your Web browser.
npm run dev
yarn dev
pnpm dev
Change port number
You can specify the port number with the port
option.
serve({
fetch: app.fetch,
port: 8787,
})
Access the raw Node.js APIs
You can access the Node.js APIs from c.env.incoming
and c.env.outgoing
.
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)
Serve static files
You can use serveStatic
to serve static files from the local file system.
import { serveStatic } from '@hono/node-server/serve-static'
app.use('/static/*', serveStatic({ root: './' }))
rewriteRequestPath
If you want to map http://localhost:3000/static/*
to ./statics
, you can use the rewriteRequestPath
option:
app.get(
'/static/*',
serveStatic({
root: './',
rewriteRequestPath: (path) =>
path.replace(/^\/static/, '/statics'),
})
)
http2
You can run hono on a Node.js http2 Server.
unencrypted http2
import { createServer } from 'node:http2'
const server = serve({
fetch: app.fetch,
createServer,
})
encrypted http2
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
Here is an example of a Dockerfile.
FROM node:20-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"]
The following steps shall be taken in advance.
- Add
"outDir": "./dist"
to thecompilerOptions
sectiontsconfig.json
. - Add
"exclude": ["node_modules"]
totsconfig.json
. - Add
"build": "tsc"
toscript
section ofpackage.json
. - Run
npm install typescript --save-dev
. - Add
"type": "module"
topackage.json
.