cianfhoghlaim/cianchosaint / .agents/skills/hono
hono
Verifiedname: hono description: Expert assistance for building lightweight web APIs with Hono. Use when users need fast HTTP servers, middleware composition, multi-runtime support (Cloudflare Workers, Node.js, Bun, Deno), or API gateway functionality.
Hono - Lightweight Web Framework
Version: 4.x | Last Updated: 2025-01
Overview
Hono is a small, fast web framework for building HTTP servers:
- Multi-Runtime: Works on Cloudflare Workers, Node.js, Bun, Deno, AWS Lambda
- TypeScript First: Full type inference and safety
- Middleware System: Composable middleware architecture
- Zero Dependencies: Minimal footprint (~12KB)
- Web Standards: Uses Request/Response API
Documentation: https://hono.dev
When to Use This Skill
Activate when users need:
- "Create a lightweight API server"
- "Build an edge function API"
- "Add middleware to HTTP routes"
- "Create a Cloudflare Workers backend"
- "Build an API gateway"
Core Concepts
1. Basic Application
import { Hono } from 'hono'
const app = new Hono()
app.get('/', (c) => {
return c.text('Hello Hono!')
})
app.get('/json', (c) => {
return c.json({ message: 'Hello', timestamp: Date.now() })
})
export default app
2. Route Parameters
const app = new Hono()
// Path parameters
app.get('/users/:id', (c) => {
const id = c.req.param('id')
return c.json({ userId: id })
})
// Multiple parameters
app.get('/posts/:postId/comments/:commentId', (c) => {
const { postId, commentId } = c.req.param()
return c.json({ postId, commentId })
})
// Optional parameters
app.get('/files/:path{.+}', (c) => {
const path = c.req.param('path')
return c.text(`File: ${path}`)
})
// Wildcard
app.get('/api/*', (c) => {
return c.text('API endpoint')
})
3. Request Handling
app.post('/users', async (c) => {
// JSON body
const body = await c.req.json()
// Form data
const formData = await c.req.formData()
// Query parameters
const page = c.req.query('page')
const { limit, offset } = c.req.queries()
// Headers
const auth = c.req.header('Authorization')
// URL info
const url = c.req.url
const path = c.req.path
const method = c.req.method
return c.json({ received: body })
})
4. Response Methods
app.get('/responses', (c) => {
// Text response
return c.text('Plain text')
// JSON response
return c.json({ data: 'value' })
// HTML response
return c.html('<h1>Hello</h1>')
// Redirect
return c.redirect('/new-location')
// Not found
return c.notFound()
// Custom status
return c.json({ error: 'Bad request' }, 400)
// With headers
return c.json(data, 200, {
'X-Custom-Header': 'value'
})
// Streaming
return c.stream(async (stream) => {
await stream.write('Hello ')
await stream.write('World')
})
})
5. Middleware
import { Hono } from 'hono'
import { logger } from 'hono/logger'
import { cors } from 'hono/cors'
import { jwt } from 'hono/jwt'
import { compress } from 'hono/compress'
const app = new Hono()
// Built-in middleware
app.use('*', logger())
app.use('*', compress())
app.use('/api/*', cors({
origin: ['http://localhost:3000'],
credentials: true,
}))
// JWT authentication
app.use('/protected/*', jwt({
secret: process.env.JWT_SECRET!,
}))
// Custom middleware
const timing = async (c, next) => {
const start = Date.now()
await next()
const ms = Date.now() - start
c.header('X-Response-Time', `${ms}ms`)
}
app.use('*', timing)
6. Validation with Zod
import { Hono } from 'hono'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'
const app = new Hono()
const createUserSchema = z.object({
name: z.string().min(1),
email: z.string().email(),
age: z.number().optional(),
})
app.post(
'/users',
zValidator('json', createUserSchema),
async (c) => {
const user = c.req.valid('json') // Fully typed!
// user: { name: string, email: string, age?: number }
const created = await db.users.create(user)
return c.json(created, 201)
}
)
// Validate query parameters
const querySchema = z.object({
page: z.coerce.number().default(1),
limit: z.coerce.number().default(10),
})
app.get(
'/posts',
zValidator('query', querySchema),
(c) => {
const { page, limit } = c.req.valid('query')
return c.json({ page, limit })
}
)
7. Route Grouping
import { Hono } from 'hono'
const app = new Hono()
// API routes group
const api = new Hono()
api.get('/users', (c) => c.json({ users: [] }))
api.get('/users/:id', (c) => c.json({ id: c.req.param('id') }))
api.post('/users', (c) => c.json({ created: true }))
// Admin routes group
const admin = new Hono()
admin.use('*', authMiddleware) // All admin routes protected
admin.get('/dashboard', (c) => c.json({ stats: {} }))
admin.get('/users', (c) => c.json({ allUsers: [] }))
// Mount groups
app.route('/api/v1', api)
app.route('/admin', admin)
// Results in:
// GET /api/v1/users
// GET /api/v1/users/:id
// POST /api/v1/users
// GET /admin/dashboard
// GET /admin/users
8. Context Variables
import { Hono } from 'hono'
type Env = {
Variables: {
user: { id: string; name: string }
requestId: string
}
}
const app = new Hono<Env>()
// Set variables in middleware
app.use('*', async (c, next) => {
c.set('requestId', crypto.randomUUID())
await next()
})
app.use('/protected/*', async (c, next) => {
const token = c.req.header('Authorization')
const user = await validateToken(token)
c.set('user', user)
await next()
})
// Access variables in handlers
app.get('/protected/profile', (c) => {
const user = c.get('user') // Typed!
const requestId = c.get('requestId')
return c.json({ user, requestId })
})
9. Error Handling
import { Hono, HTTPException } from 'hono'
const app = new Hono()
// Throw HTTP exceptions
app.get('/users/:id', async (c) => {
const user = await db.users.find(c.req.param('id'))
if (!user) {
throw new HTTPException(404, { message: 'User not found' })
}
return c.json(user)
})
// Global error handler
app.onError((err, c) => {
if (err instanceof HTTPException) {
return c.json({ error: err.message }, err.status)
}
console.error(err)
return c.json({ error: 'Internal server error' }, 500)
})
// Not found handler
app.notFound((c) => {
return c.json({ error: 'Route not found' }, 404)
})
10. BetterAuth Integration
import { Hono } from 'hono'
import { betterAuth } from 'better-auth'
import { cors } from 'hono/cors'
const auth = betterAuth({
database: { /* ... */ },
emailAndPassword: { enabled: true },
})
const app = new Hono()
app.use('/api/auth/*', cors({
origin: ['http://localhost:3000'],
credentials: true,
}))
// Mount BetterAuth routes
app.on(['GET', 'POST'], '/api/auth/*', (c) => {
return auth.handler(c.req.raw)
})
// Protected route using BetterAuth
app.use('/api/*', async (c, next) => {
const session = await auth.api.getSession({
headers: c.req.raw.headers,
})
if (!session) {
return c.json({ error: 'Unauthorized' }, 401)
}
c.set('user', session.user)
await next()
})
Runtime Adapters
Cloudflare Workers
import { Hono } from 'hono'
type Bindings = {
KV: KVNamespace
DB: D1Database
}
const app = new Hono<{ Bindings: Bindings }>()
app.get('/data', async (c) => {
const value = await c.env.KV.get('key')
return c.json({ value })
})
export default app
Node.js
import { Hono } from 'hono'
import { serve } from '@hono/node-server'
const app = new Hono()
app.get('/', (c) => c.text('Hello Node!'))
serve({
fetch: app.fetch,
port: 3000,
})
Bun
import { Hono } from 'hono'
const app = new Hono()
app.get('/', (c) => c.text('Hello Bun!'))
export default {
port: 3000,
fetch: app.fetch,
}
Built-in Middleware
| Middleware | Purpose |
|---|---|
logger() | Request logging |
cors() | CORS headers |
jwt() | JWT validation |
basicAuth() | Basic authentication |
compress() | Response compression |
cache() | Response caching |
etag() | ETag headers |
secureHeaders() | Security headers |
csrf() | CSRF protection |
Common Patterns
API Gateway
import { Hono } from 'hono'
const app = new Hono()
// Rate limiting
app.use('/api/*', rateLimiter({
windowMs: 60 * 1000,
max: 100,
}))
// Request logging
app.use('*', logger())
// Route to backend services
app.all('/api/users/*', async (c) => {
const url = new URL(c.req.url)
url.host = 'users-service.internal'
return fetch(url.toString(), c.req.raw)
})
app.all('/api/products/*', async (c) => {
const url = new URL(c.req.url)
url.host = 'products-service.internal'
return fetch(url.toString(), c.req.raw)
})
RESTful Resource
import { Hono } from 'hono'
const users = new Hono()
users.get('/', async (c) => {
const users = await db.users.findMany()
return c.json(users)
})
users.get('/:id', async (c) => {
const user = await db.users.findById(c.req.param('id'))
return user ? c.json(user) : c.notFound()
})
users.post('/', async (c) => {
const data = await c.req.json()
const user = await db.users.create(data)
return c.json(user, 201)
})
users.put('/:id', async (c) => {
const data = await c.req.json()
const user = await db.users.update(c.req.param('id'), data)
return c.json(user)
})
users.delete('/:id', async (c) => {
await db.users.delete(c.req.param('id'))
return c.json({ deleted: true })
})
export default users
Best Practices
- Use Typed Context: Define Env type for bindings and variables
- Group Related Routes: Use
new Hono()and.route()for organization - Validate Input: Use
@hono/zod-validatorfor request validation - Handle Errors Globally: Set up
onErrorandnotFoundhandlers - Use Built-in Middleware: Leverage logger, cors, jwt before custom solutions
- Keep Handlers Small: Extract business logic to separate modules
Troubleshooting
CORS Issues
- Ensure
cors()middleware is applied before route handlers - Check
originwhitelist includes client domain - Enable
credentials: trueif sending cookies
Type Errors with Context
- Define
Envtype withVariablesandBindings - Use
Hono<Env>()when creating app instance
Middleware Not Running
- Check middleware order (runs top to bottom)
- Ensure
await next()is called in custom middleware - Verify route patterns match
Cianfhoghlaim integration
The Cianfhoghlaim platform's API layer — serving curriculum data to the TanStack Start front-end, exposing the MCP server for agent integration, and routing AG-UI SSE streams — is built on Hono. Its multi-runtime support means the same API code runs on Bun during development, on Cloudflare Workers for edge deployment, and on the ARM1-OCI server for production.
The middleware composition enables:
- Pocket ID SSO —
auth.pocketId()middleware - Langfuse tracing —
tracing.langfuse()middleware (every request traced end-to-end) - Rate limiting —
rateLimit()middleware - AG-UI SSE —
mount('/agui', AGUIAdapter(agent).as_starlette_app())
The Cianfhoghlaim Hono apps are:
web/apps/cianfhoghlaim-web/src/server/router.ts— the public lakehouse APIagents/api/_cianfhoghlaim_api/— the FastAPI + Hono adapters for the oideachais web appweb/apps/tuatha-ui/src/server/— the Tuatha MMO + crypto API
Convex integration
The Tuatha MMO front-end uses Convex for real-time state sync. Hono integrates with Convex via two patterns:
HonoWithConvex (run Hono inside Convex)
import { Hono } from "hono";
import { HonoWithConvex } from "convex-helpers";
const app = new Hono();
app.get("/api/me", (c) => c.json({ user: "..." }));
// Deploy Hono as a Convex HTTP action
export default HonoWithConvex(app, "/api");
HttpRouterWithHono (call Convex from Hono)
import { Hono } from "hono";
import { HttpRouterWithHono } from "convex-helpers";
const app = new Hono();
app.get("/api/curriculum", async (c) => {
const convex = getConvexClient();
const data = await convex.query("curriculum:list");
return c.json(data);
});
// Bridge Hono routes into the Convex HTTP router
export const http = HttpRouterWithHono(app);
The canonical Cianfhoghlaim pattern is HttpRouterWithHono — Hono
runs as the public API gateway; Convex handles the
real-time subscriptions and mutations.
Resources
- Documentation: https://hono.dev
- GitHub: https://github.com/honojs/hono
- Middleware: https://hono.dev/middleware
- Examples: https://github.com/honojs/examples
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |