secondsky/claude-skills / plugins/hono-routing/skills/hono-routing
hono-routing
VerifiedType-safe Hono APIs with routing, middleware, RPC. Use for request validation, Zod/Valibot validators, or encountering middleware type inference, validation hook, RPC errors.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.2 KB |
| references/common-patterns.md | markdown | 9.5 KB |
| references/middleware-catalog.md | markdown | 9.7 KB |
| references/rpc-guide.md | markdown | 10.2 KB |
| references/setup-guide.md | markdown | 6.7 KB |
| references/top-errors.md | markdown | 10.6 KB |
| references/validation-libraries.md | markdown | 7.0 KB |
| scripts/check-versions.shexecutable | script | 1.9 KB |
| templates/context-extension.ts | script | 10.4 KB |
| templates/error-handling.ts | script | 10.0 KB |
| templates/middleware-composition.ts | script | 10.6 KB |
| templates/package.json | manifest | 778 B |
| templates/routing-patterns.ts | script | 7.0 KB |
| templates/rpc-client.tsx | other | 6.6 KB |
| templates/rpc-pattern.ts | script | 5.1 KB |
| templates/validation-valibot.ts | script | 8.4 KB |
| templates/validation-zod.ts | script | 11.0 KB |
references/middleware-catalog.md
View on GitHub# Hono Built-in Middleware Catalog
Complete reference for all built-in Hono middleware with usage examples and configuration options.
**Last Updated**: 2025-10-22
**Hono Version**: 4.12.12+
---
## Installation
All built-in middleware are included in the `hono` package. No additional dependencies required.
```bash
bun add hono@4.12.12 # preferred
# or: npm install hono@4.12.12
```
---
## Request Logging
### logger()
Logs request method, path, status, and response time.
```typescript
import { logger } from 'hono/logger'
app.use('*', logger())
```
**Output**:
```
GET /api/users 200 - 15ms
POST /api/posts 201 - 42ms
```
**Custom logger**:
```typescript
import { logger } from 'hono/logger'
app.use(
'*',
logger((message, ...rest) => {
console.log(`[Custom] ${message}`, ...rest)
})
)
```
---
## CORS
### cors()
Enables Cross-Origin Resource Sharing.
```typescript
import { cors } from 'hono/cors'
// Simple usage
app.use('*', cors())
// Custom configuration
app.use(
'/api/*',
cors({
origin: ['https://example.com', 'https://app.example.com'],
allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
allowHeaders: ['Content-Type', 'Authorization'],
exposeHeaders: ['X-Request-ID', 'X-Response-Time'],
maxAge: 600,
credentials: true,
})
)
// Dynamic origin
app.use(
'*',
cors({
origin: (origin) => {
return origin.endsWith('.example.com') ? origin : 'https://example.com'
},
})
)
```
**Options**:
- `origin`: String, array, or function
- `allowMethods`: HTTP methods array
- `allowHeaders`: Headers array
- `exposeHeaders`: Headers to expose
- `maxAge`: Preflight cache duration (seconds)
- `credentials`: Allow credentials
---
## Pretty JSON
### prettyJSON()
Formats JSON responses with indentation (development only).
```typescript
import { prettyJSON } from 'hono/pretty-json'
if (process.env.NODE_ENV === 'development') {
app.use('*', prettyJSON())
}
```
**Options**:
```typescript
app.use(
'*',
prettyJSON({
space: 2, // Indentation spaces (default: 2)
})
)
```
---
## Compression
### compress()
Compresses responses using gzip or deflate.
```typescript
import { compress } from 'hono/compress'
app.use('*', compress())
// Custom options
app.use(
'*',
compress({
encoding: 'gzip', // 'gzip' | 'deflate'
})
)
```
**Behavior**:
- Automatically detects `Accept-Encoding` header
- Skips if `Content-Encoding` already set
- Skips if response is already compressed
---
## Caching
### cache()
Sets HTTP cache headers.
```typescript
import { cache } from 'hono/cache'
app.use(
'/static/*',
cache({
cacheName: 'my-app',
cacheControl: 'max-age=3600', // 1 hour
})
)
// Conditional caching
app.use(
'/api/public/*',
cache({
cacheName: 'api-cache',
cacheControl: 'public, max-age=300', // 5 minutes
wait: true, // Wait for cache to be ready
})
)
```
**Options**:
- `cacheName`: Cache name
- `cacheControl`: Cache-Control header value
- `wait`: Wait for cache to be ready
---
## ETag
### etag()
Generates and validates ETags for responses.
```typescript
import { etag } from 'hono/etag'
app.use('/api/*', etag())
// Custom options
app.use(
'/api/*',
etag({
weak: true, // Use weak ETags (W/"...")
})
)
```
**Behavior**:
- Automatically generates ETag from response body
- Returns 304 Not Modified if ETag matches
- Works with `If-None-Match` header
---
## Security Headers
### secureHeaders()
Sets security-related HTTP headers.
```typescript
import { secureHeaders } from 'hono/secure-headers'
app.use('*', secureHeaders())
// Custom configuration
app.use(
'*',
secureHeaders({
contentSecurityPolicy: {
defaultSrc: ["'self'"],
scriptSrc: ["'self'", "'unsafe-inline'"],
styleSrc: ["'self'", "'unsafe-inline'"],
imgSrc: ["'self'", 'data:', 'https:'],
},
strictTransportSecurity: 'max-age=31536000; includeSubDomains',
xFrameOptions: 'DENY',
xContentTypeOptions: 'nosniff',
referrerPolicy: 'no-referrer',
})
)
```
**Headers set**:
- `Content-Security-Policy`
- `Strict-Transport-Security`
- `X-Frame-Options`
- `X-Content-Type-Options`
- `Referrer-Policy`
- `X-XSS-Protection` (deprecated but included)
---
## Server Timing
### timing()
Adds Server-Timing header with performance metrics.
```typescript
import { timing } from 'hono/timing'
app.use('*', timing())
// Custom timing
import { setMetric, startTime, endTime } from 'hono/timing'
app.use('*', timing())
app.get('/api/data', async (c) => {
startTime(c, 'db')
// Database query
endTime(c, 'db')
startTime(c, 'external')
// External API call
endTime(c, 'external')
setMetric(c, 'total', 150)
return c.json({ data: [] })
})
```
**Output header**:
```
Server-Timing: db;dur=45, external;dur=85, total;dur=150
```
---
## Bearer Auth
### bearerAuth()
Simple bearer token authentication.
> Always load secrets from environment variables; never hardcode.
```typescript
import { bearerAuth } from 'hono/bearer-auth'
app.use(
'/admin/*',
bearerAuth({
token: c.env.ADMIN_TOKEN, // load from env; rotate immediately if committed
})
)
// Multiple tokens
app.use(
'/api/*',
bearerAuth({
token: ['token1', 'token2', 'token3'],
})
)
// Custom error
app.use(
'/api/*',
bearerAuth({
token: 'secret',
realm: 'My API',
onError: (c) => {
return c.json({ error: 'Unauthorized' }, 401)
},
})
)
```
---
## Basic Auth
### basicAuth()
HTTP Basic authentication.
```typescript
import { basicAuth } from 'hono/basic-auth'
app.use(
'/admin/*',
basicAuth({
username: 'admin',
password: 'secret',
})
)
// Custom validation
app.use(
'/api/*',
basicAuth({
verifyUser: async (username, password, c) => {
const user = await db.findUser(username)
if (!user) return false
return await bcrypt.compare(password, user.passwordHash)
},
})
)
```
---
## JWT
### jwt()
JSON Web Token authentication.
> Always load secrets from environment variables; never hardcode.
```typescript
import { jwt } from 'hono/jwt'
app.use(
'/api/*',
jwt({
secret: c.env.JWT_SECRET, // load from env; rotate immediately if committed
})
)
// Access JWT payload
app.get('/api/profile', (c) => {
const payload = c.get('jwtPayload')
return c.json({ user: payload })
})
// Custom algorithm
app.use(
'/api/*',
jwt({
secret: 'secret',
alg: 'HS256', // HS256 (default), HS384, HS512
})
)
```
---
## Request ID
### requestId()
Generates unique request IDs.
```typescript
import { requestId } from 'hono/request-id'
app.use('*', requestId())
app.get('/', (c) => {
const id = c.get('requestId')
return c.json({ requestId: id })
})
// Custom generator
app.use(
'*',
requestId({
generator: () => `req-${Date.now()}-${Math.random()}`,
})
)
```
---
## Combine
### combine()
Combines multiple middleware into one.
```typescript
import { combine } from 'hono/combine'
import { logger } from 'hono/logger'
import { cors } from 'hono/cors'
import { compress } from 'hono/compress'
app.use('*', combine(
logger(),
cors(),
compress()
))
```
---
## Trailing Slash
### trimTrailingSlash()
Removes trailing slashes from URLs.
```typescript
import { trimTrailingSlash } from 'hono/trailing-slash'
app.use('*', trimTrailingSlash())
// /api/users/ → /api/users
```
---
## Serve Static
### serveStatic()
Serves static files (runtime-specific).
**Cloudflare Workers**:
```typescript
import { serveStatic } from 'hono/cloudflare-workers'
app.use('/static/*', serveStatic({ root: './public' }))
```
**Deno**:
```typescript
import { serveStatic } from 'hono/deno'
app.use('/static/*', serveStatic({ root: './public' }))
```
**Bun**:
```typescript
import { serveStatic } from 'hono/bun'
app.use('/static/*', serveStatic({ root: './public' }))
```
---
## Body Limit
### bodyLimit()
Limits request body size.
```typescript
import { bodyLimit } from 'hono/body-limit'
app.use(
'/api/*',
bodyLimit({
maxSize: 1024 * 1024, // 1 MB
onError: (c) => {
return c.json({ error: 'Request body too large' }, 413)
},
})
)
```
---
## Timeout
### timeout()
Sets timeout for requests.
```typescript
import { timeout } from 'hono/timeout'
app.use(
'/api/*',
timeout(5000) // 5 seconds
)
// Custom error
app.use(
'/api/*',
timeout(
3000,
(c) => c.json({ error: 'Request timeout' }, 504)
)
)
```
---
## IP Restriction
### ipRestriction()
Restricts access by IP address.
```typescript
import { ipRestriction } from 'hono/ip-restriction'
app.use(
'/admin/*',
ipRestriction(
{
allowList: ['192.168.1.0/24'],
denyList: ['10.0.0.0/8'],
},
(c) => c.json({ error: 'Forbidden' }, 403)
)
)
```
---
## Summary
| Middleware | Purpose | Common Use Case |
|------------|---------|-----------------|
| `logger()` | Request logging | Development, debugging |
| `cors()` | CORS handling | API routes |
| `prettyJSON()` | JSON formatting | Development |
| `compress()` | Response compression | All routes |
| `cache()` | HTTP caching | Static assets |
| `etag()` | ETag generation | API responses |
| `secureHeaders()` | Security headers | All routes |
| `timing()` | Performance metrics | Production monitoring |
| `bearerAuth()` | Bearer token auth | API authentication |
| `basicAuth()` | Basic auth | Admin panels |
| `jwt()` | JWT authentication | API authentication |
| `requestId()` | Request IDs | Logging, tracing |
| `combine()` | Combine middleware | Clean code |
| `trimTrailingSlash()` | URL normalization | All routes |
| `serveStatic()` | Static files | Assets |
| `bodyLimit()` | Body size limit | API routes |
| `timeout()` | Request timeout | Long-running operations |
| `ipRestriction()` | IP filtering | Admin panels |
---
**Official Documentation**: https://hono.dev/docs/guides/middleware
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |