スキーマ駆動は『型 + 実行時検証 + ドキュメント』を統合する
Zod・Valibot は TypeScript ベースのスキーマ定義+ランタイム検証ライブラリです。本記事では編集部の視点で、両者の使い方を公開情報をもとに整理します。TypeScript 上級 もご参考に。
Zod の特徴
(1) シンプルな API：z.object().parse() のチェイン。(2) z.infer：スキーマから型を導出。(3) 豊富なエコシステム：tRPC/Hono/Astro 公式対応。(4) バンドルサイズ：中程度。(5) エラーオブジェクト：構造化された詳細。
Valibot の特徴
(1) モジュラー設計：必要関数のみインポート。(2) バンドルサイズ：Zod の数分の1(公開情報をもとに)。(3) パイプライン：parse + transform を組合せ。(4) 関数型 API：object/string/number 等を import。(5) エコシステム：成長中・Zod 互換を目指す動き。
API 境界での使い方
(1) HTTP リクエスト検証：body/query/params。(2) レスポンス型生成：z.infer で。(3) OpenAPI 連携：zod-to-openapi 等。(4) 環境変数の検証：起動時にチェック。(5) 外部APIのレスポンス検証。REST API設計 もご参考に。
フォーム検証
(1) React Hook Form 連携：zodResolver。(2) サーバーアクション：Next.js での検証。(3) エラーメッセージ：i18n 対応。(4) 非同期検証：refine で API 呼出。(5) partial validation：ステップごと。
tRPC / Hono RPC との連携
(1) input/output 検証：tRPC の中核機能。(2) 型の自動同期：クライアント側。(3) エラーハンドリング：ZodError をそのまま。(4) middleware 検証：認証/権限。(5) パフォーマンス：Valibot の方が高速(公開情報をもとに)。Hono 実践 もご参考に。
選択の判断軸
(1) バンドルサイズ重視：Valibot。(2) エコシステム重視：Zod。(3) エッジ環境：Valibot。(4) 大規模プロジェクト：Zod 安定的。(5) 新規 + 軽量重視：Valibot 試す価値あり。
失敗しがちなパターン
(1) 境界以外で検証多用：パフォーマンス低下。(2> any/unknown でバイパス。(3) refine 過剰でテスト困難。(4) type と schema 二重定義。(5) エラーメッセージ未翻訳。対策は、(1)境界限定、(2)型強制、(3)refine 最小、(4)z.infer 統一、(5)i18n、です。