Help us improve
Share bugs, ideas, or general feedback.
From cloudflare
Scaffolds Hono API routes for Cloudflare Workers with Zod validation, middleware, typed bindings, error handling, and endpoint documentation. Use post-project setup to add endpoints.
npx claudepluginhub jezweb/claude-skills --plugin cloudflareHow this skill is triggered — by the user, by Claude, or both
Slash command
/cloudflare:hono-api-scaffolderThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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.
Builds ultra-fast web APIs and full-stack apps with Hono on Cloudflare Workers, Deno, Bun, Node.js. Covers routing, middleware, JSX support, RPC client for edge and BFFs.
Scaffolds and deploys Cloudflare Workers with Hono routing, Vite dev server, static assets, and D1/R2/KV bindings. Troubleshoots export errors, API conflicts, HMR, and deployments.
Guides Hono app creation, API building, middleware/auth/validation addition, routing, context usage, streaming, WebSocket, CORS, testing, SSG, and multi-runtime deployment including Cloudflare Workers.
Share bugs, ideas, or general feedback.
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.
Determine what the API needs. Either ask the user or infer from the project description. Group endpoints by resource:
Users: GET /api/users, GET /api/users/:id, POST /api/users, PUT /api/users/:id, DELETE /api/users/:id
Posts: GET /api/posts, GET /api/posts/:id, POST /api/posts, PUT /api/posts/:id
Auth: POST /api/auth/login, POST /api/auth/logout, GET /api/auth/me
One file per resource group. Use the template from assets/route-template.ts:
// src/routes/users.ts
import { Hono } from 'hono'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'
import type { Env } from '../types'
const app = new Hono<{ Bindings: Env }>()
// GET /api/users
app.get('/', async (c) => {
const db = c.env.DB
const { results } = await db.prepare('SELECT * FROM users').all()
return c.json({ users: results })
})
// GET /api/users/:id
app.get('/:id', async (c) => {
const id = c.req.param('id')
const user = await db.prepare('SELECT * FROM users WHERE id = ?').bind(id).first()
if (!user) return c.json({ error: 'Not found' }, 404)
return c.json({ user })
})
// POST /api/users
const createUserSchema = z.object({
name: z.string().min(1),
email: z.string().email(),
})
app.post('/', zValidator('json', createUserSchema), async (c) => {
const body = c.req.valid('json')
// ... insert logic
return c.json({ user }, 201)
})
export default app
Based on project needs, add from assets/middleware-template.ts:
Auth middleware — protect routes requiring authentication:
import { createMiddleware } from 'hono/factory'
import type { Env } from '../types'
export const requireAuth = createMiddleware<{ Bindings: Env }>(async (c, next) => {
const token = c.req.header('Authorization')?.replace('Bearer ', '')
if (!token) return c.json({ error: 'Unauthorized' }, 401)
// Validate token...
await next()
})
CORS — use Hono's built-in:
import { cors } from 'hono/cors'
app.use('/api/*', cors({ origin: ['https://example.com'] }))
Mount all route groups in the main entry point:
// src/index.ts
import { Hono } from 'hono'
import type { Env } from './types'
import users from './routes/users'
import posts from './routes/posts'
import auth from './routes/auth'
import { errorHandler } from './middleware/error-handler'
const app = new Hono<{ Bindings: Env }>()
// Global error handler
app.onError(errorHandler)
// Mount routes
app.route('/api/users', users)
app.route('/api/posts', posts)
app.route('/api/auth', auth)
// Health check
app.get('/api/health', (c) => c.json({ status: 'ok' }))
export default app
// src/types.ts
export interface Env {
DB: D1Database
KV: KVNamespace // if needed
R2: R2Bucket // if needed
API_SECRET: string // secrets
}
Document all endpoints. See references/endpoint-docs-template.md for the format:
## POST /api/users
Create a new user.
- **Auth**: Required (Bearer token)
- **Body**: `{ name: string, email: string }`
- **Response 201**: `{ user: User }`
- **Response 400**: `{ error: string, details: ZodError }`
Always validate request bodies with @hono/zod-validator:
import { zValidator } from '@hono/zod-validator'
app.post('/', zValidator('json', schema), async (c) => {
const body = c.req.valid('json') // fully typed
})
Install: pnpm add @hono/zod-validator zod
Use the standard error handler from assets/error-handler.ts:
export const errorHandler = (err: Error, c: Context) => {
console.error(err)
return c.json({ error: err.message }, 500)
}
API routes must return JSON errors, not redirects. fetch() follows redirects silently, then the client tries to parse HTML as JSON.
For end-to-end type safety between Worker and client:
// Worker: export the app type
export type AppType = typeof app
// Client: use hc (Hono Client)
import { hc } from 'hono/client'
import type { AppType } from '../worker/src/index'
const client = hc<AppType>('https://api.example.com')
const res = await client.api.users.$get() // fully typed
| Project size | Structure |
|---|---|
| < 10 endpoints | Single index.ts with all routes |
| 10-30 endpoints | Route files per resource (routes/users.ts) |
| 30+ endpoints | Route files + shared middleware + typed context |
| When | Read |
|---|---|
| Hono patterns, middleware, RPC | references/hono-patterns.md |
| API_ENDPOINTS.md format | references/endpoint-docs-template.md |
| File | Purpose |
|---|---|
| assets/route-template.ts | Starter route file with CRUD + Zod |
| assets/middleware-template.ts | Auth middleware template |
| assets/error-handler.ts | Standard JSON error handler |