Hono API Scaffolder

既存の Cloudflare Workers プロジェクトに構造化された API ルートを追加します。このスキルはプロジェクトシェルが存在した後（cloudflare-worker-builder または vite-flare-starter 経由）に実行され、ルートファイル、ミドルウェア、およびエンドポイントドキュメントを生成します。

ワークフロー

ステップ 1: エンドポイントを収集

API が何を必要とするかを決定します。ユーザーに質問するか、プロジェクト説明から推測します。エンドポイントをリソースでグループ化します：

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

ステップ 2: ルートファイルを作成

リソースグループごとに 1 ファイル。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

ステップ 3: ミドルウェアを追加

プロジェクト要件に基づいて assets/middleware-template.ts から追加します：

Auth ミドルウェア — 認証が必要なルートを保護します：

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 — Hono のビルトインを使用します：

import { cors } from 'hono/cors'
app.use('/api/*', cors({ origin: ['https://example.com'] }))

ステップ 4: ルートを配線

メインエントリーポイントにすべてのルートグループをマウントします：

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

ステップ 5: 型を作成

// src/types.ts
export interface Env {
  DB: D1Database
  KV: KVNamespace      // if needed
  R2: R2Bucket         // if needed
  API_SECRET: string   // secrets
}

ステップ 6: API_ENDPOINTS.md を生成

すべてのエンドポイントをドキュメント化します。フォーマットについては references/endpoint-docs-template.md を参照してください：

## 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 }`

キーパターン

Zod バリデーション

@hono/zod-validator でリクエストボディを常にバリデートします：

import { zValidator } from '@hono/zod-validator'
app.post('/', zValidator('json', schema), async (c) => {
  const body = c.req.valid('json')  // fully typed
})

インストール: pnpm add @hono/zod-validator zod

エラーハンドリング

assets/error-handler.ts の標準エラーハンドラーを使用します：

export const errorHandler = (err: Error, c: Context) => {
  console.error(err)
  return c.json({ error: err.message }, 500)
}

API ルートは JSON エラーを返す必要があり、リダイレクトではありません。 fetch() はリダイレクトを自動的にフォローしため、クライアントが HTML を JSON として解析しようとします。

RPC 型安全性

Worker とクライアント間のエンドツーエンド型安全性のために：

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

ルートグループ対単一ファイル

プロジェクトサイズ	構造
10 未満のエンドポイント	すべてのルートを含む単一の index.ts
10～30 エンドポイント	リソースごとのルートファイル（routes/users.ts）
30 以上のエンドポイント	ルートファイル + 共有ミドルウェア + 型付きコンテキスト

リファレンスファイル

内容	読むファイル
Hono パターン、ミドルウェア、RPC	references/hono-patterns.md
API_ENDPOINTS.md フォーマット	references/endpoint-docs-template.md

アセット

ファイル	目的
assets/route-template.ts	Zod 付きの CRUD スターターロートファイル
assets/middleware-template.ts	Auth ミドルウェアテンプレート
assets/error-handler.ts	標準 JSON エラーハンドラー