Hono API Scaffolder 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. Workflow Step 1: Gather Endpoints 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 Step 2: Create Route Files 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 Step 3: Add Middleware 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' ] } ) ) Step 4: Wire Routes 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 Step 5: Create Types // src/types.ts export interface Env { DB : D1Database KV : KVNamespace // if needed R2 : R2Bucket // if needed API_SECRET : string // secrets } Step 6: Generate API_ENDPOINTS.md 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 }Key Patterns Zod Validation 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 Error Handling 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. RPC Type Safety 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 Route Groups vs Single File 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 Reference Files When Read Hono patterns, middleware, RPC references/hono-patterns.md API_ENDPOINTS.md format references/endpoint-docs-template.md Assets 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