Hono Routing

Hono Routing & Middleware

Status: Production Ready ✅ Last Updated: 2025-10-22 Production Tested: Used across Cloudflare Workers, Deno, Bun, and Node.js applications

---

Auto-Trigger Keywords

Claude Code automatically discovers this skill when you mention:

Primary Keywords

• hono
• hono routing
• hono middleware
• hono rpc
• hono validator
• @hono/hono

Secondary Keywords

• hono routes
• hono typed routes
• hono context
• hono error handling
• hono request validation
• zod validator hono
• valibot validator hono
• hono client
• type-safe api
• hono middleware composition
• c.req.valid
• c.json
• hono hooks

Error-Based Keywords

• "middleware response not typed"
• "hono validation failed"
• "hono rpc type inference"
• "hono context type"
• "HTTPException hono"
• "hono route params"
• "hono middleware chain"
• "validator hook hono"
• "hono error handler"

---

What This Skill Does

This skill provides comprehensive knowledge for building type-safe APIs with Hono, focusing on routing patterns, middleware composition, request validation, RPC client/server patterns, error handling, and context management.

Core Capabilities

✅ Routing Patterns - Route parameters, query params, wildcards, route grouping ✅ Middleware Composition - Built-in middleware, custom middleware, chaining strategies ✅ Request Validation - Zod, Valibot, Typia, ArkType validators with custom error hooks ✅ Typed Routes (RPC) - Type-safe client/server communication with full type inference ✅ Error Handling - HTTPException, onError hooks, custom error responses ✅ Context Extension - c.set/c.get patterns, custom context types, type-safe variables

---

Known Issues This Skill Prevents

Issue	Why It Happens	Source	How Skill Fixes It
RPC Type Inference Slow	Complex type instantiation from many routes	hono#guides/rpc	Use route variable pattern: const route = app.get(...)
Middleware Response Not Typed	RPC mode doesn't infer middleware responses	hono#2719	Export specific route types for RPC client
Validation Hook Confusion	Multiple validator libraries, different hook patterns	Context7 research	Provides consistent patterns for all validators
HTTPException Misuse	Throwing errors without proper status/message	Official docs	Shows proper HTTPException patterns
Context Type Safety	c.set/c.get without proper typing	Official docs	Demonstrates type-safe context extension
Error After Next	Not checking c.error after middleware	Official docs	Shows proper error checking pattern
Query/Param Validation	Direct access without validation	Official docs	Always use c.req.valid() after validation
Middleware Order	Incorrect middleware execution order	Official docs	Explains middleware flow and chaining

---

When to Use This Skill

✅ Use When:

• Building APIs with Hono (any runtime: Cloudflare Workers, Deno, Bun, Node.js)
• Setting up request validation with Zod, Valibot, or other validators
• Creating type-safe RPC client/server communication
• Implementing custom middleware or middleware chains
• Handling errors with HTTPException or custom error handlers
• Extending Hono context with custom variables
• Optimizing route type inference for better IDE performance
• Migrating from Express or other frameworks to Hono

❌ Don't Use When:

• Setting up Cloudflare Workers infrastructure (use cloudflare-worker-base instead)
• Building Next.js applications (use cloudflare-nextjs or Next.js docs)
• Need database integration (use cloudflare-d1, cloudflare-kv, etc.)
• Need authentication setup (use clerk-auth or other auth skills)

---

Quick Usage Example

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

const app = new Hono()

// Route with validation
const schema = z.object({
  name: z.string(),
  age: z.number(),
})

app.post('/user', zValidator('json', schema), (c) => {
  const data = c.req.valid('json')
  return c.json({ success: true, data })
})

// Type-safe RPC export
export type AppType = typeof app

Result: Fully type-safe API with validation, ready for RPC client

Full instructions: See SKILL.md

---

Package Versions (Verified 2025-10-22)

Package	Version	Status
hono	4.10.2	✅ Latest stable
zod	4.1.12	✅ Latest stable
valibot	1.1.0	✅ Latest stable
@hono/zod-validator	0.7.4	✅ Latest stable
@hono/valibot-validator	0.5.3	✅ Latest stable
@hono/typia-validator	0.1.2	✅ Latest stable
@hono/arktype-validator	2.0.1	✅ Latest stable

---

Dependencies

Prerequisites: None (framework-agnostic)

Integrates With:

• cloudflare-worker-base (optional) - For Cloudflare Workers setup
• clerk-auth (optional) - For authentication middleware
• ai-sdk-core (optional) - For AI-powered endpoints

---

File Structure

hono-routing/
├── SKILL.md                      # Complete documentation
├── README.md                     # This file
├── templates/
│   ├── routing-patterns.ts       # Route params, query, wildcards
│   ├── middleware-composition.ts # Middleware chaining, built-ins
│   ├── validation-zod.ts         # Zod validation with hooks
│   ├── validation-valibot.ts     # Valibot validation
│   ├── rpc-pattern.ts            # Type-safe RPC client/server
│   ├── error-handling.ts         # HTTPException, onError, custom
│   ├── context-extension.ts      # c.set/c.get, custom types
│   └── package.json              # All dependencies
├── references/
│   ├── middleware-catalog.md     # Built-in Hono middleware
│   ├── validation-libraries.md   # Zod vs Valibot vs others
│   ├── rpc-guide.md              # RPC pattern deep dive
│   └── top-errors.md             # Common errors + solutions
└── scripts/
    └── check-versions.sh         # Verify package versions

---

Official Documentation

• Hono: https://hono.dev
• Hono Routing: https://hono.dev/docs/api/routing
• Hono Middleware: https://hono.dev/docs/guides/middleware
• Hono Validation: https://hono.dev/docs/guides/validation
• Hono RPC: https://hono.dev/docs/guides/rpc
• Context7 Library: /llmstxt/hono_dev_llms-full_txt

---

Related Skills

• cloudflare-worker-base - Cloudflare Workers + Hono setup
• clerk-auth - Authentication middleware patterns
• react-hook-form-zod - Client-side form validation
• ai-sdk-core - AI-powered API endpoints

---

Contributing

Found an issue or have a suggestion?

• Open an issue: https://github.com/secondsky/claude-skills/issues
• See SKILL.md for detailed documentation

---

License

MIT License - See main repo LICENSE file

---

Production Tested: Cloudflare Workers, Deno, Bun, Node.js Token Savings: ~56% Error Prevention: 100% Ready to use! See SKILL.md for complete setup.