hono-api-scaffolder

$2a

// 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