Hono Web Framework Skill

Provide comprehensive guidance for developing web applications and APIs with the Hono framework.

Overview

Hono is a lightweight, fast web framework built on Web Standards that runs on multiple JavaScript runtimes:

Cloudflare Workers
Deno
Bun
Vercel
AWS Lambda
Node.js

Key characteristics:

Small bundle size (hono/tiny preset < 14kB)
Fast RegExpRouter
Zero dependencies option
First-class TypeScript support
Web Standards API only

Workflow

Follow this sequence when assisting with Hono development:

Identify runtime target - Ask the user about their target platform (Cloudflare, Deno, Bun, Node.js, etc.)
Search documentation - Use hono search <query> to find relevant documentation topics
Load details - Use hono docs <path> to retrieve specific documentation sections
Implement - Write code following patterns in references/patterns.md
Test locally - Use hono request for quick testing or hono serve for development server
Optimize - Run hono optimize before production deployment

Project Creation

Use create-hono CLI

Create new Hono projects using the official CLI:

# npm
npm create hono@latest

# Bun
bunx create-hono

# Deno
deno run -A npm:create-hono

Prompt the user to choose:

Runtime target: Cloudflare Workers, Deno, Bun, Node.js, Vercel, AWS Lambda, etc.
Template: Basic, with JSX, with validation, etc.
Package manager: npm, yarn, pnpm, bun

Project Structure

Recommend this structure:

my-hono-app/
├── src/
│   ├── index.ts          # Main application entry
│   ├── routes/           # Route handlers
│   ├── middleware/       # Custom middleware
│   └── lib/              # Utilities and helpers
├── test/                 # Test files
├── package.json
├── tsconfig.json
└── [runtime-config]      # wrangler.toml, vercel.json, etc.

Hono CLI (@hono/cli)

The official Hono CLI provides commands designed for AI-assisted development.

Installation

Install as a dev dependency:

npm install -D @hono/cli

CLI Commands

hono docs [path]

Retrieve documentation as Markdown:

# Get all docs
hono docs

# Get specific section
hono docs concepts/middleware

Use when needing to reference official documentation during development.

hono search

Return JSON-formatted search results:

hono search "middleware"
hono search "routing"

Use when needing to discover relevant documentation paths.

hono request [file]

Test Hono applications without starting a server:

# Basic request
hono request src/index.ts

# POST with data
hono request -X POST -d '{"name":"John"}' src/index.ts

# Custom path
hono request -P /api/users src/index.ts

# Combined flags
hono request -X POST -P /api/users -d '{"name":"Alice"}' src/index.ts

Flags:

-X <METHOD>: HTTP method (GET, POST, PUT, DELETE, etc.)
-P <PATH>: Request path
-d <DATA>: Request body

Use when testing APIs during development without server startup overhead.

hono serve [file]

Launch application on localhost:7070:

# Basic serve
hono serve src/index.ts

# With middleware injection (no code modification needed)
hono serve --use logger --use compress src/index.ts

Use when quick local testing or development with dynamic middleware is needed.

hono optimize [entry]

Generate optimized build using PreparedRegExpRouter:

hono optimize src/index.ts

# Output to specific file
hono optimize src/index.ts -o dist/optimized.js

Benefits:

~38% smaller bundle size
16.5× faster initialization
Pre-compiles route information as hardcoded strings

Use when preparing for production deployment, especially for edge runtimes where bundle size matters.

Development Guidance

Code Patterns

Reference references/patterns.md for:

Routing patterns (basic, path params, query params, nested)
Middleware usage (global, route-specific, built-in options)
Validation with Zod
Error handling
Database integration examples
Testing patterns with Vitest

TypeScript Configuration

Reference references/typescript.md for:

Runtime-specific tsconfig.json setups
Type safety with Bindings and Variables
JSX/TSX configuration
Path aliases
Common TypeScript issues and solutions

Deployment

Reference references/deployment.md for platform-specific deployment instructions:

Cloudflare Workers
Vercel
Deno Deploy
AWS Lambda
Bun
Node.js

Always recommend running hono optimize before deployment.

HonoX Meta-Framework

Suggest HonoX when the user needs:

Server-side rendered applications
File-based routing
Islands architecture (partial hydration)
Vite integration

Create HonoX project:

npm create hono@latest -- --template honox

Key features:

File-based routing in app/routes/
Islands in app/islands/
Server functions
Vite integration

When to Use This Skill

Activate this skill when the user:

Creates a new Hono project
Asks about Hono CLI tools (docs, search, request, serve, optimize)
Tests Hono APIs without starting a server
Optimizes Hono apps for production deployment
Works with Hono routing, middleware, or configuration
Deploys Hono to any platform
Migrates to Hono from another framework
Works with HonoX or full-stack Hono applications
Configures TypeScript for Hono
Sets up testing for Hono apps
Works with runtime-specific Hono features (Cloudflare, Deno, Bun, etc.)
Requests performance optimization strategies

Key Principles

Proactively use Hono CLI commands (hono docs, hono search, hono request) during development
Recommend hono optimize for production deployments
Suggest appropriate middleware and patterns for the use case
Consider suggesting HonoX for full-stack needs
Use create-hono CLI for new projects rather than manual setup
Verify package.json scripts match the runtime environment
Follow the workflow: Identify → Search → Load docs → Implement → Test → Optimize

Resources

Official docs: https://hono.dev
GitHub: https://github.com/honojs/hono
Hono CLI: https://github.com/honojs/hono/tree/main/packages/cli
HonoX: https://github.com/honojs/honox
Examples: https://github.com/honojs/examples