Hono Core Knowledge
Full Reference: See advanced.md for WebSocket integration patterns including Cloudflare Workers, Node.js ws library, Bun WebSocket, room management, and message protocols.
Deep Knowledge: Use mcp__documentation__fetch_docs with technology: hono for comprehensive documentation.
Basic Setup
import { Hono } from 'hono'; import { cors } from 'hono/cors'; import { logger } from 'hono/logger';
const app = new Hono();
app.use('', logger()); app.use('', cors());
app.route('/api/users', userRoutes);
export default app;
Route Patterns
import { Hono } from 'hono'; import { zValidator } from '@hono/zod-validator'; import { z } from 'zod';
const app = new Hono();
const userSchema = z.object({ name: z.string(), email: z.string().email(), });
app.get('/', async (c) => { const users = await db.users.findMany(); return c.json(users); });
app.post('/', zValidator('json', userSchema), async (c) => { const data = c.req.valid('json'); const user = await db.users.create(data); return c.json(user, 201); });
app.get('/:id', async (c) => { const id = c.req.param('id'); const user = await db.users.find(id); if (!user) return c.json({ error: 'Not found' }, 404); return c.json(user); });
Middleware
import { createMiddleware } from 'hono/factory';
const auth = createMiddleware(async (c, next) => { const token = c.req.header('Authorization')?.split(' ')[1]; if (!token) return c.json({ error: 'Unauthorized' }, 401);
c.set('user', await verifyToken(token)); await next(); });
app.get('/protected', auth, (c) => {
const user = c.get('user');
return c.json({ message: Hello ${user.name} });
});
Multi-Runtime Support
// Cloudflare Workers export default app;
// Node.js import { serve } from '@hono/node-server'; serve(app);
// Bun export default { fetch: app.fetch, port: 3000 };
When NOT to Use This Skill
-
Node.js-Only Applications: Use Express, Fastify, or NestJS
-
Enterprise DI Patterns: Use NestJS for dependency injection
-
Deno-Specific Features: Use Oak or Fresh
-
Long-Running Processes: Edge runtimes have execution time limits
-
File System Operations: Edge environments have limited FS access
-
Database-Heavy Logic: Consider traditional servers for complex ORM
Anti-Patterns
Anti-Pattern Why It's Bad Correct Approach
Using Node.js-specific APIs in edge code Won't work on Cloudflare Workers Use Web APIs (fetch, Response, etc.)
Not handling context properly State leaks between requests Use c.set() and c.get()
Importing large dependencies Exceeds edge bundle size limits Use tree-shakeable libraries
Using fs module Not available in edge runtimes Use KV storage or external APIs
Blocking operations in handlers Exceeds edge execution time Use async operations
Hardcoding runtime assumptions Portability issues Check c.env for runtime bindings
Quick Troubleshooting
Issue Likely Cause Solution
"Module not found" in production Wrong runtime adapter Use correct import for runtime
Request context undefined Accessing outside request scope Use context c within handlers
Middleware not executing Wrong order or missing await next()
Ensure middleware calls await next()
CORS errors in production Missing CORS middleware Add app.use('*', cors())
Validation not working Zod validator not applied Use zValidator('json', schema)
Cold start timeouts Bundle too large Optimize imports
Production Readiness
Security Setup
import { Hono } from 'hono'; import { cors } from 'hono/cors'; import { secureHeaders } from 'hono/secure-headers';
const app = new Hono();
app.use('', secureHeaders()); app.use('', cors({ origin: process.env.CORS_ORIGINS?.split(',') || [], credentials: true, }));
Error Handling
import { HTTPException } from 'hono/http-exception';
export function errorHandler(err: Error, c: Context) { if (err instanceof HTTPException) { return c.json({ error: err.message }, err.status); } return c.json({ error: 'Internal error' }, 500); }
app.onError(errorHandler);
Health Checks
health.get('/health', (c) => c.json({ status: 'healthy' }));
health.get('/ready', async (c) => { try { await db.query('SELECT 1'); return c.json({ status: 'ready', database: 'connected' }); } catch (error) { return c.json({ status: 'not ready' }, 503); } });
Testing
import { describe, it, expect } from 'vitest'; import app from '../src/app';
describe('API', () => { it('GET /health returns healthy', async () => { const res = await app.request('/health'); expect(res.status).toBe(200); }); });
Monitoring Metrics
Metric Target
Cold start time < 50ms
Response time (p99) < 20ms
Error rate < 0.1%
Memory usage < 128MB
Checklist
-
Secure headers middleware
-
CORS properly configured
-
Rate limiting for API routes
-
Zod validation for inputs
-
Request ID tracing
-
Structured JSON logging
-
Custom error handler
-
Health/readiness endpoints
-
Graceful shutdown (Node.js)
-
Tests with app.request()
Reference Documentation
-
Middleware Patterns
-
Validation