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

Quick Troubleshooting

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

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