1# Workers Frameworks
2 
3## Hono (Recommended)
4 
5Workers-native web framework with excellent TypeScript support and middleware ecosystem.
6 
7```bash
8npm install hono
9```
10 
11### Basic Setup
12 
13```typescript
14import { Hono } from 'hono';
15 
16const app = new Hono();
17 
18app.get('/', (c) => c.text('Hello World!'));
19app.post('/api/users', async (c) => {
20  const body = await c.req.json();
21  return c.json({ id: 1, ...body }, 201);
22});
23 
24export default app;
25```
26 
27### Typed Environment
28 
29```typescript
30import type { Env } from './.wrangler/types/runtime';
31 
32const app = new Hono<{ Bindings: Env }>();
33 
34app.get('/data', async (c) => {
35  const value = await c.env.MY_KV.get('key');  // Fully typed
36  return c.text(value || 'Not found');
37});
38```
39 
40### Middleware
41 
42```typescript
43import { cors } from 'hono/cors';
44import { logger } from 'hono/logger';
45 
46app.use('*', logger());
47app.use('/api/*', cors({ origin: '*' }));
48 
49// Custom middleware
50app.use('/protected/*', async (c, next) => {
51  const auth = c.req.header('Authorization');
52  if (!auth?.startsWith('Bearer ')) return c.text('Unauthorized', 401);
53  await next();
54});
55```
56 
57### Request Validation (Zod)
58 
59```typescript
60import { zValidator } from '@hono/zod-validator';
61import { z } from 'zod';
62 
63const schema = z.object({
64  name: z.string().min(1),
65  email: z.string().email(),
66});
67 
68app.post('/users', zValidator('json', schema), async (c) => {
69  const validated = c.req.valid('json');  // Type-safe, validated data
70  return c.json({ id: 1, ...validated });
71});
72```
73 
74**Error handling**: Automatic 400 response with validation errors
75 
76### Route Groups
77 
78```typescript
79const api = new Hono().basePath('/api');
80 
81api.get('/users', (c) => c.json([]));
82api.post('/users', (c) => c.json({ id: 1 }));
83 
84app.route('/', api);  // Mounts at /api/*
85```
86 
87### Error Handling
88 
89```typescript
90app.onError((err, c) => {
91  console.error(err);
92  return c.json({ error: err.message }, 500);
93});
94 
95app.notFound((c) => c.json({ error: 'Not Found' }, 404));
96```
97 
98### Accessing ExecutionContext
99 
100```typescript
101export default {
102  fetch(request: Request, env: Env, ctx: ExecutionContext) {
103    return app.fetch(request, env, ctx);
104  },
105};
106 
107// In route handlers:
108app.get('/log', (c) => {
109  c.executionCtx.waitUntil(logRequest(c.req));
110  return c.text('OK');
111});
112```
113 
114### OpenAPI/Swagger (Hono OpenAPI)
115 
116```typescript
117import { OpenAPIHono, createRoute, z } from '@hono/zod-openapi';
118 
119const app = new OpenAPIHono();
120 
121const route = createRoute({
122  method: 'get',
123  path: '/users/{id}',
124  request: { params: z.object({ id: z.string() }) },
125  responses: {
126    200: { description: 'User found', content: { 'application/json': { schema: z.object({ id: z.string() }) } } },
127  },
128});
129 
130app.openapi(route, (c) => {
131  const { id } = c.req.valid('param');
132  return c.json({ id });
133});
134 
135app.doc('/openapi.json', { openapi: '3.0.0', info: { version: '1.0.0', title: 'API' } });
136```
137 
138### Testing with Hono
139 
140```typescript
141import { describe, it, expect } from 'vitest';
142import app from '../src/index';
143 
144describe('API', () => {
145  it('GET /', async () => {
146    const res = await app.request('/');
147    expect(res.status).toBe(200);
148    expect(await res.text()).toBe('Hello World!');
149  });
150});
151```
152 
153## Other Frameworks
154 
155### itty-router (Minimalist)
156 
157```typescript
158import { Router } from 'itty-router';
159 
160const router = Router();
161 
162router.get('/users/:id', ({ params }) => new Response(params.id));
163 
164export default { fetch: router.handle };
165```
166 
167**Use case**: Tiny bundle size (~500 bytes), simple routing needs
168 
169### Worktop (Advanced)
170 
171```typescript
172import { Router } from 'worktop';
173 
174const router = new Router();
175 
176router.add('GET', '/users/:id', (req, res) => {
177  res.send(200, { id: req.params.id });
178});
179 
180router.listen();
181```
182 
183**Use case**: Advanced routing, built-in CORS/cache utilities
184 
185## Framework Comparison
186 
187| Framework | Bundle Size | TypeScript | Middleware | Validation | Best For |
188|-----------|-------------|------------|------------|------------|----------|
189| Hono | ~12KB | Excellent | Rich | Zod | Production apps |
190| itty-router | ~500B | Good | Basic | Manual | Minimal APIs |
191| Worktop | ~8KB | Good | Advanced | Manual | Complex routing |
192 
193## See Also
194 
195- [Patterns](./patterns.md) - Common workflows
196- [API](./api.md) - Runtime APIs
197- [Gotchas](./gotchas.md) - Framework-specific issues
198