Hono API 構築スキル

HonoとZodによる型安全なAPI開発の全ワークフローを提供します。

いつ使うか

このスキルは以下の場合に使用してください：

• 新しいCRUD APIエンドポイントの作成
• リクエストバリデーションの追加
• 型安全なクライアント-サーバー通信の構築
• APIのテストと最適化
• Honoドキュメントの検索

ワークフロー

1. API エンドポイントの作成

// apps/server/src/routes/admin/users.ts
import { Hono } from 'hono'
import { zValidator } from '@hono/zod-validator'
import { CreateUserSchema } from '@repo/schemas/request/admin/users'
import { db } from '@repo/database'

const app = new Hono()

// POST /users - 作成
app.post('/', zValidator('json', CreateUserSchema), async (c) => {
  const data = c.req.valid('json')  // 型安全
  const user = await db.user.create({ data })
  return c.json({ user }, 201)
})

// GET /users/:id - 取得
app.get('/:id', async (c) => {
  const id = c.req.param('id')
  const user = await db.user.findUnique({ where: { id } })
  if (!user) return c.json({ error: 'Not found' }, 404)
  return c.json({ user })
})

// RPCのために型をエクスポート
export type AppType = typeof app

詳細パターン（エラーハンドリング、ページネーション、複雑なクエリ）は crud-operations.md を参照してください。

2. バリデーションの追加

// packages/schemas/src/request/admin/users.ts
import { z } from 'zod'
import type { Prisma } from '@repo/database'

export const CreateUserSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
  age: z.number().int().positive().optional(),
}) satisfies z.ZodType<Prisma.UserCreateInput>  // Prisma型と同期

export type CreateUserInput = z.infer<typeof CreateUserSchema>

詳細パターン（カスタムバリデーション、複雑な変換、エラーメッセージ）は validation.md を参照してください。

3. RPC クライアントのセットアップ

// apps/admin/src/utils/hc.ts
import { hc } from 'hono/client'
import type { AppType } from '@repo/server'

export const client = hc<AppType>('/api')

// apps/admin/src/swr/users/use-user.ts
export function useUser(id: string) {
  return useSWR(['user', id], async () => {
    return await parseResponse(client.admin.users[':id'].$get({ param: { id } })) // 完全に型付けされている
  })
}

詳細パターン（型推論、エラーハンドリング、複数API統合）は rpc-client.md を参照してください。

4. Hono CLI でテスト・最適化

# ドキュメントを検索
hono search "middleware"

# ドキュメントを表示
hono docs /docs/guides/middleware

# サーバー起動なしでテスト
hono request -P /api/users apps/server/src/index.ts
hono request -P /api/users -X POST -d '{"name":"Alice"}' apps/server/src/index.ts

# 本番デプロイ前に最適化（ファイルサイズ38%削減、初期化16.5倍高速化）
hono optimize apps/server/src/index.ts -o dist/server.js

詳細ワークフロー（CLIコマンド、最適化、自動化パターン）は hono-cli.md を参照してください。

重要ルール

API 作成

• c.notFound()

  は使用しない（RPC型を壊す）
• 常にステータスコードを明示的に指定
• クライアント用に

  AppType

  をエクスポート
• response スキーマは visibility + deriveDto で構築（

  .pick()

  は使わない）

バリデーション

• スキーマ名は PascalCase（

  CreateUserSchema

  ）
• スキーマは

  packages/schemas/

  に定義
• バリデート済みデータ取得には

  c.req.valid()

  を使用
• クエリパラメータには

  z.coerce

  を使用（文字列→数値の変換）

RPC クライアント

• サーバーから

  AppType

  をエクスポート
• クライアントで型をインポート（値ではない:

  import type

  ）
• 型安全性のために

  hc<AppType>()

  を使用
• レスポンス型には

  InferResponseType

  を使用

Hono CLI

• 開発サーバー不要:

  hono request

  は内部で

  app.request()

  を使用
• 環境の競合とサーバーの乱立を防ぐ
• テストには常に

  hono request

  を優先

• hono optimize

  は本番デプロイ前に実行（開発中は不要）

詳細パターン

詳細な実装パターンについては references を参照してください：

• crud-operations.md - CRUD操作、エラーハンドリング、ページネーション
• validation.md - カスタムバリデーション、複雑な変換、エラーメッセージ
• rpc-client.md - 型推論、エラーハンドリング、複数API
• hono-cli.md - CLIワークフロー、最適化、自動化