hono

What is hono?

Hono is a small, simple, and fast web framework for building web applications and APIs in Node.js. It is designed to be lightweight and efficient, making it suitable for high-performance applications.

What are hono's main functionalities?

Basic Routing

Hono allows you to define routes for your web application. In this example, a basic GET route is defined that responds with 'Hello, Hono!' when accessed.

const { Hono } = require('hono');
const app = new Hono();

app.get('/', (c) => c.text('Hello, Hono!'));

app.listen(3000);

Middleware Support

Hono supports middleware, allowing you to execute code before your route handlers. This example demonstrates a simple logger middleware that logs the request method and URL.

const { Hono } = require('hono');
const app = new Hono();

const logger = (c, next) => {
  console.log(`${c.req.method} ${c.req.url}`);
  return next();
};

app.use(logger);

app.get('/', (c) => c.text('Hello, Hono!'));

app.listen(3000);

Error Handling

Hono provides a way to handle errors globally. In this example, an error is thrown in the route handler, and the global error handler responds with a 500 status code and a message.

const { Hono } = require('hono');
const app = new Hono();

app.get('/', (c) => {
  throw new Error('Something went wrong!');
});

app.onError((err, c) => {
  c.status(500);
  return c.text('Internal Server Error');
});

app.listen(3000);

Other packages similar to hono

express

Express is a widely-used web framework for Node.js, known for its simplicity and flexibility. It offers a robust set of features for web and mobile applications, including routing, middleware support, and more. Compared to Hono, Express has a larger community and more extensive documentation, but Hono aims to be more lightweight and faster.

koa

Koa is a web framework designed by the team behind Express. It aims to be a smaller, more expressive, and more robust foundation for web applications and APIs. Koa uses async functions to help eliminate callback hell and improve error handling. Compared to Hono, Koa is more modern and has a different approach to middleware, using a stack-like structure.

fastify

Fastify is a web framework highly focused on providing the best developer experience with the least overhead and a powerful plugin architecture. It is designed for high performance and low overhead. Compared to Hono, Fastify is more feature-rich and has a more extensive ecosystem, but Hono aims to be simpler and more lightweight.

README

---

Hono - [炎] means flame🔥 in Japanese - is a small, simple, and ultrafast web framework for Cloudflare Workers or Service Worker based serverless such as Fastly Compute@Edge.

import { Hono } from 'hono'
const app = new Hono()

app.get('/', (c) => c.text('Hono!!'))

app.fire()

Features

• Ultrafast - the router does not use linear loops.
• Zero-dependencies - using only Service Worker and Web Standard API.
• Middleware - built-in middleware and ability to extend with your own middleware.
• TypeScript - first-class TypeScript support.
• Optimized - for Cloudflare Workers.

Benchmark

Hono is fastest, compared to other routers for Cloudflare Workers.

hono - trie-router(default) x 737,602 ops/sec ±3.65% (67 runs sampled)
hono - regexp-router x 1,188,203 ops/sec ±6.42% (60 runs sampled)
itty-router x 163,970 ops/sec ±3.05% (91 runs sampled)
sunder x 344,468 ops/sec ±0.87% (97 runs sampled)
worktop x 222,044 ops/sec ±2.13% (85 runs sampled)
Fastest is hono - regexp-router
✨  Done in 84.04s.

Why so fast?

Routers used in Hono are really smart.

• TrieRouter(default) - Implemented with Trie tree structure.
• RegExpRouter - Match routes with one big Regex made before dispatching at once.

Hono in 1 minute

A demonstration to create an application for Cloudflare Workers with Hono.

Not only fast

Hono is fast. But not only fast.

Write Less, do more

Built-in middleware make "Write Less, do more" in reality. You can use a lot of middleware without writing code from scratch. Below are examples.

• Basic Authentication
• Cookie parsing / serializing
• CORS
• ETag
• GraphQL Server
• JWT Authentication
• Logger
• Mustache template engine (Only for Cloudflare Workers)
• JSON pretty printing
• Serving static files (Only for Cloudflare Workers)

To enable logger and Etag middleware with just this code.

import { Hono } from 'hono'
import { etag } from 'hono/etag'
import { logger } from 'hono/logger'

const app = new Hono()
app.use('*', etag(), (logger())

And, the routing of Hono is so flexible. It's easy to construct large web applications.

import { Hono, Route } from 'hono'
import { cors } from 'hono/cors'

const app = new Hono()

const v1 = new Route()
v1.get('/posts', (c) => {
  return c.text('list pots')
})
  .post('/posts', cors(), (c) => {
    return c.text('created!', 201)
  })
  .get('/posts/:id', (c) => {
    const id = c.req.param('id')
    return c.text(`your id is ${id}`)
  })

app.route('/v1', v1)

Web Standard

Request and Response object used in Hono are extensions of the Web Standard Fetch API. If you are familiar with that, you don't need to know more than that.

Developer Experience

Hono provides fine "Developer Experience". Easy access to Request/Response thanks to the Context object. Above all, Hono is written in TypeScript. So, Hono has "Types"!

For example, the named path parameters will be literal types.

Install

You can install Hono from the npm registry.

npm install hono

Methods

An instance of Hono has these methods.

• app.HTTP_METHOD([path,] handler|middleware...)
• app.all([path,] handler|middleware...)
• app.route(path, [Route])
• app.use([path,] middleware)
• app.notFound(handler)
• app.onError(err, handler)
• app.fire()
• app.fetch(request, env, event)
• app.request(path, options)

Routing

Basic

// HTTP Methods
app.get('/', (c) => c.text('GET /'))
app.post('/', (c) => c.text('POST /'))

// Wildcard
app.get('/wild/*/card', (c) => {
  return c.text('GET /wild/*/card')
})

// Any HTTP methods
app.all('/hello', (c) => c.text('Any Method /hello'))

Named Parameter

app.get('/user/:name', (c) => {
  const name = c.req.param('name')
  ...
})

Regexp

app.get('/post/:date{[0-9]+}/:title{[a-z]+}', (c) => {
  const date = c.req.param('date')
  const title = c.req.param('title')
  ...
})

Chained route

app
  .get('/endpoint', (c) => {
    return c.text('GET /endpoint')
  })
  .post((c) => {
    return c.text('POST /endpoint')
  })
  .delete((c) => {
    return c.text('DELETE /endpoint')
  })

no strict

If strict is set false, /helloand/hello/ are treated the same.

const app = new Hono({ strict: false }) // Default is true

app.get('/hello', (c) => c.text('/hello or /hello/'))

async/await

app.get('/fetch-url', async (c) => {
  const response = await fetch('https://example.com/')
  return c.text(`Status is ${response.status}`)
})

Route

Route object enables Nested route.

const book = new Route()

book.get('/', (c) => c.text('List Books')) // GET /book
book.get('/:id', (c) => {
  // GET /book/:id
  const id = c.req.param('id')
  return c.text('Get Book: ' + id)
})
book.post('/', (c) => c.text('Create Book')) // POST /book

app.route('/book', book)

Middleware

Middleware operate after/before executing Handler. We can get Response before dispatching or manipulate Response after dispatching.

Definition of Middleware

• Handler - should return Response object.
• Middleware - should return nothing, do await next()

Built-in Middleware

Hono has built-in middleware.

import { Hono } from 'hono'
import { poweredBy } from 'hono/powered-by'
import { logger } from 'hono/logger'
import { basicAuth } from 'hono/basicAuth'

const app = new Hono()

app.use('*', poweredBy())
app.use('*', logger())

app.use(
  '/auth/*',
  basicAuth({
    username: 'hono',
    password: 'acoolproject',
  })
)

Available built-in middleware is listed on src/middleware.

Custom Middleware

You can write your own middleware.

// Custom logger
app.use('*', async (c, next) => {
  console.log(`[${c.req.method}] ${c.req.url}`)
  await next()
})

// Add a custom header
app.use('/message/*', async (c, next) => {
  await next()
  c.header('x-message', 'This is middleware!')
})

app.get('/message/hello', (c) => c.text('Hello Middleware!'))

Not Found

app.notFound for customizing Not Found Response.

app.notFound((c) => {
  return c.text('Custom 404 Message', 404)
})

Error Handling

app.onError handle the error and return the customized Response.

app.onError((err, c) => {
  console.error(`${err}`)
  return c.text('Custom Error Message', 500)
})

Context

To handle Request and Response, you can use Context object.

c.req

// Get Request object
app.get('/hello', (c) => {
  const userAgent = c.req.headers.get('User-Agent')
  ...
})

// Shortcut to get a header value
app.get('/shortcut', (c) => {
  const userAgent = c.req.header('User-Agent')
  ...
})

// Query params
app.get('/search', (c) => {
  const query = c.req.query('q')
  ...
})

// Captured params
app.get('/entry/:id', (c) => {
  const id = c.req.param('id')
  ...
})

Shortcuts for Response

app.get('/welcome', (c) => {
  // Set headers
  c.header('X-Message', 'Hello!')
  c.header('Content-Type', 'text/plain')

  // Set HTTP status code
  c.status(201)

  // Return the response body
  return c.body('Thank you for comming')
})

The Response is the same as below.

new Response('Thank you for comming', {
  status: 201,
  statusText: 'Created',
  headers: {
    'X-Message': 'Hello',
    'Content-Type': 'text/plain',
  },
})

c.text()

Render text as Content-Type:text/plain.

app.get('/say', (c) => {
  return c.text('Hello!')
})

c.json()

Render JSON as Content-Type:application/json.

app.get('/api', (c) => {
  return c.json({ message: 'Hello!' })
})

c.html()

Render HTML as Content-Type:text/html.

app.get('/', (c) => {
  return c.html('<h1>Hello! Hono!</h1>')
})

c.notFound()

Return the Not Found Response.

app.get('/notfound', (c) => {
  return c.notFound()
})

c.redirect()

Redirect, default status code is 302.

app.get('/redirect', (c) => c.redirect('/'))
app.get('/redirect-permanently', (c) => c.redirect('/', 301))

c.res

// Response object
app.use('/', (c, next) => {
  next()
  c.res.headers.append('X-Debug', 'Debug message')
})

c.event

// FetchEvent object
app.use('*', async (c, next) => {
  c.event.waitUntil(
    ...
  )
  await next()
})

c.env

// Environment object for Cloudflare Workers
app.get('*', async c => {
  const counter = c.env.COUNTER
  ...
})

fire

app.fire() do this.

addEventListener('fetch', (event) => {
  event.respondWith(this.handleEvent(event))
})

fetch

app.fetch for Cloudflare Module Worker syntax.

export default {
  fetch(request: Request, env: Env, event: FetchEvent) {
    return app.fetch(request, env, event)
  },
}

or just do:

export default app

request

request is a useful method for testing.

test('GET /hello is ok', async () => {
  const res = await app.request('http://localhost/hello')
  expect(res.status).toBe(200)
})

Cloudflare Workers with Hono

Using Wrangler, you can develop the application locally and publish it with few commands.

Let's write your first code for Cloudflare Workers with Hono.

1. wrangler init

Initialize as a wrangler project.

mkdir hono-example
cd hono-example
npx wrangler init -y

2. npm install hono

Install hono from the npm registry.

npm init -y
npm i hono

3. Write your app

Edit src/index.ts. Only 4 lines!!

// src/index.ts
import { Hono } from 'hono'
const app = new Hono()

app.get('/', (c) => c.text('Hello! Hono!'))

app.fire()

4. Run

Run the development server locally. Then, access http://127.0.0.1:8787/ in your Web browser.

npx wrangler dev

5. Publish

Deploy to Cloudflare. That's all!

npx wrangler publish ./src/index.ts

Starter template

You can start making your Cloudflare Workers application with the starter template. It is really minimal using TypeScript, esbuild, Miniflare, and Jest.

To generate a project skelton, run this command.

npx create-cloudflare my-app https://github.com/honojs/hono-minimal

Examples

• Hono Examples - https://github.com/honojs/examples

Related projects

Implementation of the original router TrieRouter is inspired by goblin. RegExpRouter is inspired by Router::Boom. API design is inspired by express and koa. itty-router, Sunder, and worktop are the other routers or frameworks for Cloudflare Workers.

• express - https://github.com/expressjs/express
• koa - https://github.com/koajs/koa
• itty-router - https://github.com/kwhitley/itty-router
• Sunder - https://github.com/SunderJS/sunder
• goblin - https://github.com/bmf-san/goblin
• worktop - https://github.com/lukeed/worktop
• Router::Boom - https://github.com/tokuhirom/Router-Boom

Contributing

Contributions Welcome! You can contribute in the following ways.

• Write or fix documents
• Write code of middleware
• Fix bugs
• Refactor the code
• etc.

Contributors

Thanks to all contributors! Especially, @metrue and @usualoma!

Author

Yusuke Wada https://github.com/yusukebe

License

Distributed under the MIT License. See LICENSE for more information.