hono-api-scaffolder

Name: hono-api-scaffolder
Author: jezweb

937stars96forks

How to install hono-api-scaffolder?

jezweb/claude-skills/hono-api-scaffolder

$npx -y skills add jezweb/claude-skills --skill hono-api-scaffolder

Installs into the current project.

Summary

Scaffold Hono API routes for Cloudflare Workers. Produces route files, middleware, typed bindings, Zod validation, error handling, and API_ENDPOINTS.md documentation. Use after a project is set up with cloudflare-worker-builder or vite-flare-starter, when you need to add API rout

Files · 1

View on GitHub

SKILL.md

1	# Hono API Scaffolder
2
3	Add structured API routes to an existing Cloudflare Workers project. This skill runs AFTER the project shell exists (via cloudflare-worker-builder or vite-flare-starter) and produces route files, middleware, and endpoint documentation.
4
5	## Workflow
6
7	### Step 1: Gather Endpoints
8
9	Determine what the API needs. Either ask the user or infer from the project description. Group endpoints by resource:
10
11	```
12	Users: GET /api/users, GET /api/users/:id, POST /api/users, PUT /api/users/:id, DELETE /api/users/:id
13	Posts: GET /api/posts, GET /api/posts/:id, POST /api/posts, PUT /api/posts/:id
14	Auth: POST /api/auth/login, POST /api/auth/logout, GET /api/auth/me
15	```
16
17	### Step 2: Create Route Files
18
19	One file per resource group. Use the template from [assets/route-template.ts](assets/route-template.ts):
20
21	```typescript
22	// src/routes/users.ts
23	import { Hono } from 'hono'
24	import { zValidator } from '@hono/zod-validator'
25	import { z } from 'zod'
26	import type { Env } from '../types'
27
28	const app = new Hono<{ Bindings: Env }>()
29
30	// GET /api/users
31	app.get('/', async (c) => {
32	const db = c.env.DB
33	const { results } = await db.prepare('SELECT * FROM users').all()
34	return c.json({ users: results })
35	})
36
37	// GET /api/users/:id
38	app.get('/:id', async (c) => {
39	const id = c.req.param('id')
40	const user = await db.prepare('SELECT * FROM users WHERE id = ?').bind(id).first()
41	if (!user) return c.json({ error: 'Not found' }, 404)
42	return c.json({ user })
43	})
44
45	// POST /api/users
46	const createUserSchema = z.object({
47	name: z.string().min(1),
48	email: z.string().email(),
49	})
50
51	app.post('/', zValidator('json', createUserSchema), async (c) => {
52	const body = c.req.valid('json')
53	// ... insert logic
54	return c.json({ user }, 201)
55	})
56
57	export default app
58	```
59
60	### Step 3: Add Middleware
61
62	Based on project needs, add from [assets/middleware-template.ts](assets/middleware-template.ts):
63
64	Auth middleware — protect routes requiring authentication:
65	```typescript
66	import { createMiddleware } from 'hono/factory'
67	import type { Env } from '../types'
68
69	export const requireAuth = createMiddleware<{ Bindings: Env }>(async (c, next) => {
70	const token = c.req.header('Authorization')?.replace('Bearer ', '')
71	if (!token) return c.json({ error: 'Unauthorized' }, 401)
72	// Validate token...
73	await next()
74	})
75	```
76
77	CORS — use Hono's built-in:
78	```typescript
79	import { cors } from 'hono/cors'
80	app.use('/api/*', cors({ origin: ['https://example.com'] }))
81	```
82
83	### Step 4: Wire Routes
84
85	Mount all route groups in the main entry point:
86
87	```typescript
88	// src/index.ts
89	import { Hono } from 'hono'
90	import type { Env } from './types'
91	import users from './routes/users'
92	import posts from './routes/posts'
93	import auth from './routes/auth'
94	import { errorHandler } from './middleware/error-handler'
95
96	const app = new Hono<{ Bindings: Env }>()
97
98	// Global error handler
99	app.onError(errorHandler)
100
101	// Mount routes
102	app.route('/api/users', users)
103	app.route('/api/posts', posts)
104	app.route('/api/auth', auth)
105
106	// Health check
107	app.get('/api/health', (c) => c.json({ status: 'ok' }))
108
109	export default app
110	```
111
112	### Step 5: Create Types
113
114	```typescript
115	// src/types.ts
116	export interface Env {
117	DB: D1Database
118	KV: KVNamespace // if needed
119	R2: R2Bucket // if needed
120	API_SECRET: string // secrets
121	}
122	```
123
124	### Step 6: Generate API_ENDPOINTS.md
125
126	Document all endpoints. See [references/endpoint-docs-template.md](references/endpoint-docs-template.md) for the format:
127
128	```markdown
129	## POST /api/users
130	Create a new user.
131	- Auth: Required (Bearer token)
132	- Body: `{ name: string, email: string }`
133	- Response 201: `{ user: User }`
134	- Response 400: `{ error: string, details: ZodError }`
135	```
136
137	## Key Patterns
138
139	### Zod Validation
140
141	Always validate request bodies with `@hono/zod-validator`:
142
143	```typescript
144	import { zValidator } from '@hono/zod-validator'
145	app.post('/', zValidator('json', schema), async (c) => {
146	const body = c.req.valid('json') // fully typed
147	})
148	```
149
150	Install: `pnpm add @hono/zod-validator zod`
151
152	### Error Handling
153
154	Use the standard error handler from [assets/error-handler.ts](assets/error-handler.ts):
155
156	```typescript
157	export const errorHandler = (err: Error, c: Context) => {
158	console.error(err)
159	return c.json({ error: err.message }, 500)
160	}
161	```
162
163	API routes must return JSON errors, not redirects. `fetch()` follows redirects silently, then the client tries to parse HTML as JSON.
164
165	### RPC Type Safety
166
167	For end-to-end type safety between Worker and client:
168
169	```typescript
170	// Worker: export the app type
171	export type AppType = typeof app
172
173	// Client: use hc

People who liked this also viewed

6 picks

Type

hono-api-scaffolder

937stars96forks

View on GitHub

How to install hono-api-scaffolder?

jezweb/claude-skills/hono-api-scaffolder

$npx -y skills add jezweb/claude-skills --skill hono-api-scaffolder

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Hono API Scaffolder
2
3	Add structured API routes to an existing Cloudflare Workers project. This skill runs AFTER the project shell exists (via cloudflare-worker-builder or vite-flare-starter) and produces route files, middleware, and endpoint documentation.
4
5	## Workflow
6
7	### Step 1: Gather Endpoints
8
9	Determine what the API needs. Either ask the user or infer from the project description. Group endpoints by resource:
10
11	```
12	Users: GET /api/users, GET /api/users/:id, POST /api/users, PUT /api/users/:id, DELETE /api/users/:id
13	Posts: GET /api/posts, GET /api/posts/:id, POST /api/posts, PUT /api/posts/:id
14	Auth: POST /api/auth/login, POST /api/auth/logout, GET /api/auth/me
15	```
16
17	### Step 2: Create Route Files
18
19	One file per resource group. Use the template from [assets/route-template.ts](assets/route-template.ts):
20
21	```typescript
22	// src/routes/users.ts
23	import { Hono } from 'hono'
24	import { zValidator } from '@hono/zod-validator'
25	import { z } from 'zod'
26	import type { Env } from '../types'
27
28	const app = new Hono<{ Bindings: Env }>()
29
30	// GET /api/users
31	app.get('/', async (c) => {
32	const db = c.env.DB
33	const { results } = await db.prepare('SELECT * FROM users').all()
34	return c.json({ users: results })
35	})
36
37	// GET /api/users/:id
38	app.get('/:id', async (c) => {
39	const id = c.req.param('id')
40	const user = await db.prepare('SELECT * FROM users WHERE id = ?').bind(id).first()
41	if (!user) return c.json({ error: 'Not found' }, 404)
42	return c.json({ user })
43	})
44
45	// POST /api/users
46	const createUserSchema = z.object({
47	name: z.string().min(1),
48	email: z.string().email(),
49	})
50
51	app.post('/', zValidator('json', createUserSchema), async (c) => {
52	const body = c.req.valid('json')
53	// ... insert logic
54	return c.json({ user }, 201)
55	})
56
57	export default app
58	```
59
60	### Step 3: Add Middleware
61
62	Based on project needs, add from [assets/middleware-template.ts](assets/middleware-template.ts):
63
64	Auth middleware — protect routes requiring authentication:
65	```typescript
66	import { createMiddleware } from 'hono/factory'
67	import type { Env } from '../types'
68
69	export const requireAuth = createMiddleware<{ Bindings: Env }>(async (c, next) => {
70	const token = c.req.header('Authorization')?.replace('Bearer ', '')
71	if (!token) return c.json({ error: 'Unauthorized' }, 401)
72	// Validate token...
73	await next()
74	})
75	```
76
77	CORS — use Hono's built-in:
78	```typescript
79	import { cors } from 'hono/cors'
80	app.use('/api/*', cors({ origin: ['https://example.com'] }))
81	```
82
83	### Step 4: Wire Routes
84
85	Mount all route groups in the main entry point:
86
87	```typescript
88	// src/index.ts
89	import { Hono } from 'hono'
90	import type { Env } from './types'
91	import users from './routes/users'
92	import posts from './routes/posts'
93	import auth from './routes/auth'
94	import { errorHandler } from './middleware/error-handler'
95
96	const app = new Hono<{ Bindings: Env }>()
97
98	// Global error handler
99	app.onError(errorHandler)
100
101	// Mount routes
102	app.route('/api/users', users)
103	app.route('/api/posts', posts)
104	app.route('/api/auth', auth)
105
106	// Health check
107	app.get('/api/health', (c) => c.json({ status: 'ok' }))
108
109	export default app
110	```
111
112	### Step 5: Create Types
113
114	```typescript
115	// src/types.ts
116	export interface Env {
117	DB: D1Database
118	KV: KVNamespace // if needed
119	R2: R2Bucket // if needed
120	API_SECRET: string // secrets
121	}
122	```
123
124	### Step 6: Generate API_ENDPOINTS.md
125
126	Document all endpoints. See [references/endpoint-docs-template.md](references/endpoint-docs-template.md) for the format:
127
128	```markdown
129	## POST /api/users
130	Create a new user.
131	- Auth: Required (Bearer token)
132	- Body: `{ name: string, email: string }`
133	- Response 201: `{ user: User }`
134	- Response 400: `{ error: string, details: ZodError }`
135	```
136
137	## Key Patterns
138
139	### Zod Validation
140
141	Always validate request bodies with `@hono/zod-validator`:
142
143	```typescript
144	import { zValidator } from '@hono/zod-validator'
145	app.post('/', zValidator('json', schema), async (c) => {
146	const body = c.req.valid('json') // fully typed
147	})
148	```
149
150	Install: `pnpm add @hono/zod-validator zod`
151
152	### Error Handling
153
154	Use the standard error handler from [assets/error-handler.ts](assets/error-handler.ts):
155
156	```typescript
157	export const errorHandler = (err: Error, c: Context) => {
158	console.error(err)
159	return c.json({ error: err.message }, 500)
160	}
161	```
162
163	API routes must return JSON errors, not redirects. `fetch()` follows redirects silently, then the client tries to parse HTML as JSON.
164
165	### RPC Type Safety
166
167	For end-to-end type safety between Worker and client:
168
169	```typescript
170	// Worker: export the app type
171	export type AppType = typeof app
172
173	// Client: use hc

People who liked this also viewed

6 picks

Type