hono-api-scaffolder

Hono API スキャフォルダー

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

ワークフロー

Step 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

Step 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

Step 3: ミドルウェアを追加する

プロジェクトの要件に応じて、assets/middleware-template.ts から追加します。

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

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'] }))

Step 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

Step 5: 型を作成する

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

Step 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	CRUD + Zod を含むルートファイルのひな形
assets/middleware-template.ts	認証ミドルウェアのテンプレート
assets/error-handler.ts	標準の JSON エラーハンドラー