Skill

Review

Audit score 70

hono

yusukebe/hono-skill

Build Hono web applications with routing, middleware, validation, and JSX support.

What is hono?

Hono is a lightweight web framework for building fast APIs and web applications. Use this skill when building Hono apps, working with routing/middleware, or testing endpoints with `npx hono request`. Triggers automatically when code imports from 'hono' or mentions Hono.

Define routes with HTTP methods (GET, POST, PUT, DELETE, PATCH) and path parameters
Apply middleware for CORS, authentication, logging, compression, and security headers
Validate request data using Zod or Valibot schemas with full TypeScript typing
Build server-rendered UIs with JSX components and custom renderers
Test endpoints without starting an HTTP server using `npx hono request`
Access request data (params, query, headers, body) and set response status/headers

How to install hono

npx skills add https://github.com/yusukebe/hono-skill --skill hono

Prerequisites

Node.js environment with npm or compatible package manager
TypeScript configured with jsx option set to 'react-jsx' and jsxImportSource set to 'hono/jsx' for JSX files

Claude Code

Cursor

Windsurf

Cline

How to use hono

1.Import Hono and create an app instance: `const app = new Hono()`
2.Define routes using `app.get()`, `app.post()`, etc. with handler functions
3.Add middleware with `app.use()` for cross-cutting concerns like logging or auth
4.Use `c.req` to access request data and `c.json()`, `c.html()`, etc. to send responses
5.Test endpoints with `npx hono request [file] -P /path` or `npx hono request [file] -X POST -P /api/users -d '{...}'`
6.For Cloudflare Workers bindings, use `npx workers-fetch` instead of `hono request`

Use cases

Good for

Building REST APIs with request validation and error handling
Creating server-rendered web applications with JSX templates
Adding authentication, CORS, and security middleware to routes
Testing API endpoints during development without manual HTTP requests
Deploying to Cloudflare Workers with environment bindings (KV, D1, R2)

Who it's for

Backend developers building APIs and web services
Full-stack developers using server-rendered JSX
Teams deploying to Cloudflare Workers or edge runtimes
Developers needing lightweight, fast web frameworks with TypeScript support

hono FAQ

How do I test endpoints without starting a server?

Use `npx hono request [file] -P /path` for GET requests or `npx hono request [file] -X POST -P /api/users -d '{...}'` for POST. Do not pass credentials in CLI arguments; use environment variables instead.

How do I add authentication to routes?

Use the `basicAuth` or `bearerAuth` middleware from 'hono/auth', or create custom middleware with `createMiddleware` to check tokens in the Authorization header.

Can I use JSX with Hono?

Yes. Configure tsconfig.json with `"jsx": "react-jsx"` and `"jsxImportSource": "hono/jsx"`, then use `.tsx` files. Use `c.render()` to return JSX components.

How do I validate request data?

Use `zValidator` from '@hono/zod-validator' or `sValidator` from '@hono/standard-validator' as middleware, then access validated data with `c.req.valid('json')`.

Does `hono request` work with Cloudflare Workers bindings?

No. For endpoints requiring KV, D1, or R2 bindings, use `npx workers-fetch` instead of `hono request`.

Full instructions (SKILL.md)

Source of truth, from yusukebe/hono-skill.

name: hono description: Use when building Hono web applications or when the user asks about Hono APIs, routing, middleware, JSX, validation, testing, or streaming. TRIGGER when code imports from 'hono' or 'hono/*', or user mentions Hono. Use `npx hono request` to test endpoints.

Hono Skill

Build Hono web applications. This skill provides inline API knowledge for AI. Use npx hono request to test endpoints. If the hono-docs MCP server is configured, prefer its tools for the latest documentation over the inline reference.

Hono CLI Usage

Request Testing

Test endpoints without starting an HTTP server. Uses app.request() internally.

# GET request
npx hono request [file] -P /path

# POST request with JSON body
npx hono request [file] -X POST -P /api/users -d '{"name": "test"}'

Note: Do not pass credentials directly in CLI arguments. Use environment variables for sensitive values. hono request does not support Cloudflare Workers bindings (KV, D1, R2, etc.). When bindings are required, use workers-fetch instead:

npx workers-fetch /path
npx workers-fetch -X POST -H "Content-Type:application/json" -d '{"name":"test"}' /api/users

Hono API Reference

App Constructor

import { Hono } from 'hono'

const app = new Hono()

// With TypeScript generics
type Env = {
  Bindings: { DATABASE: D1Database; KV: KVNamespace }
  Variables: { user: User }
}
const app = new Hono<Env>()

Routing Methods

app.get('/path', handler)
app.post('/path', handler)
app.put('/path', handler)
app.delete('/path', handler)
app.patch('/path', handler)
app.options('/path', handler)
app.all('/path', handler) // all HTTP methods
app.on('PURGE', '/path', handler) // custom method
app.on(['PUT', 'DELETE'], '/path', handler) // multiple methods

Routing Patterns

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

// Multiple params
app.get('/posts/:id/comments/:commentId', (c) => {
  const { id, commentId } = c.req.param()
})

// Optional parameters
app.get('/api/animal/:type?', (c) => c.text('Animal!'))

// Wildcards
app.get('/wild/*/card', (c) => c.text('Wildcard'))

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

// Chained routes
app
  .get('/endpoint', (c) => c.text('GET'))
  .post((c) => c.text('POST'))
  .delete((c) => c.text('DELETE'))

Route Grouping

// Using route()
const api = new Hono()
api.get('/users', (c) => c.json([]))

const app = new Hono()
app.route('/api', api) // mounts at /api/users

// Using basePath()
const app = new Hono().basePath('/api')
app.get('/users', (c) => c.json([])) // GET /api/users

Error Handling

app.notFound((c) => c.json({ message: 'Not Found' }, 404))

app.onError((err, c) => {
  console.error(err)
  return c.json({ message: 'Internal Server Error' }, 500)
})

Context (c)

Response Methods

c.text('Hello') // text/plain
c.json({ message: 'Hello' }) // application/json
c.html('<h1>Hello</h1>') // text/html
c.redirect('/new-path') // 302 redirect
c.redirect('/new-path', 301) // 301 redirect
c.body('raw body', 200, headers) // raw response
c.notFound() // 404 response

Headers & Status

c.status(201)
c.header('X-Custom', 'value')
c.header('Cache-Control', 'no-store')

Variables (request-scoped data)

// In middleware
c.set('user', { id: 1, name: 'Alice' })

// In handler
const user = c.get('user')
// or
const user = c.var.user

Environment (Cloudflare Workers)

const value = await c.env.KV.get('key')
const db = c.env.DATABASE
c.executionCtx.waitUntil(promise)

Renderer

app.use(async (c, next) => {
  c.setRenderer((content) =>
    c.html(
      <html><body>{content}</body></html>
    )
  )
  await next()
})

app.get('/', (c) => c.render(<h1>Hello</h1>))

HonoRequest (c.req)

c.req.param('id') // path parameter
c.req.param() // all path params as object
c.req.query('page') // query string parameter
c.req.query() // all query params as object
c.req.queries('tags') // multiple values: ?tags=A&tags=B → ['A', 'B']
c.req.header('Authorization') // request header
c.req.header() // all headers (keys are lowercase)

// Body parsing
await c.req.json() // parse JSON body
await c.req.text() // parse text body
await c.req.formData() // parse as FormData
await c.req.parseBody() // parse multipart/form-data or urlencoded
await c.req.arrayBuffer() // parse as ArrayBuffer
await c.req.blob() // parse as Blob

// Validated data (used with validator middleware)
c.req.valid('json')
c.req.valid('query')
c.req.valid('form')
c.req.valid('param')

// Properties
c.req.url // full URL string
c.req.path // pathname
c.req.method // HTTP method
c.req.raw // underlying Request object

Middleware

Using Built-in Middleware

import { cors } from 'hono/cors'
import { logger } from 'hono/logger'
import { basicAuth } from 'hono/basic-auth'
import { prettyJSON } from 'hono/pretty-json'
import { secureHeaders } from 'hono/secure-headers'
import { etag } from 'hono/etag'
import { compress } from 'hono/compress'
import { poweredBy } from 'hono/powered-by'
import { timing } from 'hono/timing'
import { cache } from 'hono/cache'
import { bearerAuth } from 'hono/bearer-auth'
import { jwt } from 'hono/jwt'
import { csrf } from 'hono/csrf'
import { ipRestriction } from 'hono/ip-restriction'
import { bodyLimit } from 'hono/body-limit'
import { requestId } from 'hono/request-id'
import { methodOverride } from 'hono/method-override'
import { trailingSlash, trimTrailingSlash } from 'hono/trailing-slash'

// Registration
app.use(logger()) // all routes
app.use('/api/*', cors()) // specific path
app.post('/api/*', basicAuth({ username: 'admin', password: 'secret' }))

Custom Middleware

// Inline
app.use(async (c, next) => {
  const start = Date.now()
  await next()
  const elapsed = Date.now() - start
  c.res.headers.set('X-Response-Time', `${elapsed}ms`)
})

// Reusable with createMiddleware
import { createMiddleware } from 'hono/factory'

const auth = createMiddleware(async (c, next) => {
  const token = c.req.header('Authorization')
  if (!token) return c.json({ error: 'Unauthorized' }, 401)
  await next()
})

app.use('/api/*', auth)

Middleware Execution Order

Middleware executes in registration order. await next() calls the next middleware/handler, and code after next() runs on the way back:

Request → mw1 before → mw2 before → handler → mw2 after → mw1 after → Response

app.use(async (c, next) => {
  // before handler
  await next()
  // after handler
})

Validation

Validation targets: json, form, query, header, param, cookie.

Zod Validator

import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'

const schema = z.object({
  title: z.string().min(1),
  body: z.string()
})

app.post('/posts', zValidator('json', schema), (c) => {
  const data = c.req.valid('json') // fully typed
  return c.json(data, 201)
})

Valibot / Standard Schema Validator

import { sValidator } from '@hono/standard-validator'
import * as v from 'valibot'

const schema = v.object({ name: v.string(), age: v.number() })

app.post('/users', sValidator('json', schema), (c) => {
  const data = c.req.valid('json')
  return c.json(data, 201)
})

JSX

Setup

In tsconfig.json:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "hono/jsx"
  }
}

Or use pragma: /** @jsxImportSource hono/jsx */

Important: Files using JSX must have a .tsx extension. Rename .ts to .tsx or the compiler will fail.

Components

import type { PropsWithChildren } from 'hono/jsx'

const Layout = (props: PropsWithChildren) => (
  <html>
    <head>
      <title>My App</title>
    </head>
    <body>{props.children}</body>
  </html>
)

const UserCard = ({ name }: { name: string }) => (
  <div class="card">
    <h2>{name}</h2>
  </div>
)

app.get('/', (c) => {
  return c.html(
    <Layout>
      <UserCard name="Alice" />
    </Layout>
  )
})

jsxRenderer Middleware

Use jsxRenderer middleware for layouts. See npx hono docs /docs/middleware/builtin/jsx-renderer for details.

Async Components

const UserList = async () => {
  const users = await fetchUsers()
  return (
    <ul>
      {users.map((u) => (
        <li>{u.name}</li>
      ))}
    </ul>
  )
}

Fragments

const Items = () => (
  <>
    <li>Item 1</li>
    <li>Item 2</li>
  </>
)

Streaming

import { stream, streamText, streamSSE } from 'hono/streaming'

// Basic stream
app.get('/stream', (c) => {
  return stream(c, async (stream) => {
    stream.onAbort(() => console.log('Aborted'))
    await stream.write(new Uint8Array([0x48, 0x65]))
    await stream.pipe(readableStream)
  })
})

// Text stream
app.get('/stream-text', (c) => {
  return streamText(c, async (stream) => {
    await stream.writeln('Hello')
    await stream.sleep(1000)
    await stream.write('World')
  })
})

// Server-Sent Events
app.get('/sse', (c) => {
  return streamSSE(c, async (stream) => {
    let id = 0
    while (true) {
      await stream.writeSSE({
        data: JSON.stringify({ time: new Date().toISOString() }),
        event: 'time-update',
        id: String(id++)
      })
      await stream.sleep(1000)
    }
  })
})

Testing with app.request()

Test endpoints without starting an HTTP server:

// GET
const res = await app.request('/posts')
expect(res.status).toBe(200)
expect(await res.json()).toEqual({ posts: [] })

// POST with JSON
const res = await app.request('/posts', {
  method: 'POST',
  body: JSON.stringify({ title: 'Hello' }),
  headers: { 'Content-Type': 'application/json' }
})

// POST with FormData
const formData = new FormData()
formData.append('name', 'Alice')
const res = await app.request('/users', { method: 'POST', body: formData })

// With mock env (Cloudflare Workers bindings)
const res = await app.request('/api/data', {}, { KV: mockKV, DATABASE: mockDB })

// Using Request object
const req = new Request('http://localhost/api', { method: 'DELETE' })
const res = await app.request(req)

Hono Client (RPC)

Type-safe API client using shared types between server and client.

IMPORTANT: Routes MUST be chained for type inference to work. Without chaining, the client cannot infer route types.

// Server: routes MUST be chained to preserve types
const route = app
  .post('/posts', zValidator('json', schema), (c) => {
    return c.json({ ok: true }, 201)
  })
  .get('/posts', (c) => {
    return c.json({ posts: [] })
  })
export type AppType = typeof route

// Client: use hc() with the exported type
import { hc } from 'hono/client'
import type { AppType } from './server'

const client = hc<AppType>('http://localhost:8787/')
const res = await client.posts.$post({ json: { title: 'Hello' } })
const data = await res.json() // fully typed

Type utilities:

import type { InferRequestType, InferResponseType } from 'hono/client'

type ReqType = InferRequestType<typeof client.posts.$post>
type ResType = InferResponseType<typeof client.posts.$post, 200>

Helpers

Helpers are utility functions imported from hono/<helper-name>:

import { getConnInfo } from 'hono/conninfo'
import { getCookie, setCookie, deleteCookie } from 'hono/cookie'
import { css, Style } from 'hono/css'
import { createFactory } from 'hono/factory'
import { html, raw } from 'hono/html'
import { stream, streamText, streamSSE } from 'hono/streaming'
import { testClient } from 'hono/testing'
import { upgradeWebSocket } from 'hono/cloudflare-workers' // or other adapter

Available helpers: Accepts, Adapter, ConnInfo, Cookie, css, Dev, Factory, html, JWT, Proxy, Route, SSG, Streaming, Testing, WebSocket.

For details, use npx hono docs /docs/helpers/<helper-name>.

Factory

Use createFactory to define Env once and share it across app, middleware, and handlers:

import { createFactory } from 'hono/factory'

const factory = createFactory<Env>()

// Create app (Env type is inherited)
const app = factory.createApp()

// Create middleware (Env type is inherited, no need to pass generics)
const mw = factory.createMiddleware(async (c, next) => {
  await next()
})

// Create handlers separately (preserves type inference)
const handlers = factory.createHandlers(logger(), (c) => c.json({ message: 'Hello' }))
app.get('/api', ...handlers)

Best Practices

Write handlers inline in route definitions for proper type inference of path params.
Use app.route() to organize large apps by feature, not Rails-style controllers.
Use createFactory() to share Env type across app, middleware, and handlers.
Use c.set()/c.get() to pass data between middleware and handlers.
Chain validators for multiple request parts (param + query + json).
Export app type for RPC: export type AppType = typeof routes
Use app.request() for testing — no server startup needed.

Adapters

Hono runs on multiple runtimes. The default export works for Cloudflare Workers, Deno, and Bun. For Node.js, use the Node adapter:

// Cloudflare Workers / Deno / Bun
export default app

// Node.js
import { serve } from '@hono/node-server'
serve(app)

Related skills

More from yusukebe/hono-skill and the wider catalog.

find-skills

Official

vercel-labs/skills

Discover and install agent skills to extend your coding agent's capabilities on demand

2270k installs

frontend-design

Official

anthropics/skills

Build visually distinctive UI with opinionated aesthetic direction, typography, and layout choices that avoid templated defaults.

608k installsAudited

vercel-react-best-practices

Official

vercel-labs/agent-skills

70 React/Next.js performance rules from Vercel Engineering, prioritized by impact for writing, reviewing, and refactoring code.

514k installsAudited

agent-browser

Official

vercel-labs/agent-browser

Fast browser automation CLI for AI agents — navigate, click, scrape, screenshot, and test via Chrome CDP

498k installs

web-design-guidelines

Official

vercel-labs/agent-skills

Review UI code against Web Interface Guidelines for accessibility, UX, and design best practices

427k installs

finetuning

Official

microsoft/azure-skills

Fine-tune models on Azure AI Foundry with SFT, DPO, or RFT training methods.

424k installs

hono

What is hono?

How to install hono

How to use hono

Use cases

hono FAQ

name: hono description: Use when building Hono web applications or when the user asks about Hono APIs, routing, middleware, JSX, validation, testing, or streaming. TRIGGER when code imports from 'hono' or 'hono/*', or user mentions Hono. Use npx hono request to test endpoints.

Hono Skill

Hono CLI Usage

Request Testing

Hono API Reference

App Constructor

Routing Methods

Routing Patterns

Route Grouping

Error Handling

Context (c)

Response Methods

Headers & Status

Variables (request-scoped data)

Environment (Cloudflare Workers)

Renderer

HonoRequest (c.req)

Middleware

Using Built-in Middleware

Custom Middleware

Middleware Execution Order

Validation

Zod Validator

Valibot / Standard Schema Validator

JSX

Setup

Components

jsxRenderer Middleware

Async Components

Fragments

Streaming

Testing with app.request()

Hono Client (RPC)

Helpers

Factory

Best Practices

Adapters

Related skills

find-skills

frontend-design

vercel-react-best-practices

agent-browser

web-design-guidelines

finetuning

name: hono description: Use when building Hono web applications or when the user asks about Hono APIs, routing, middleware, JSX, validation, testing, or streaming. TRIGGER when code imports from 'hono' or 'hono/*', or user mentions Hono. Use `npx hono request` to test endpoints.