Zod入門 — TypeScriptで実行時の入力検証を型と一緒に書く

TypeScriptの型はコンパイル後に消えるため、APIレスポンスやフォーム入力を型注釈だけでは守れません。Zodがその境界で何をしてくれるのか、スキーマ1つで検証と型の両方が手に入る仕組みを整理します。

Zodの導入手順と、動かす前に確認しておきたいtsconfigの設定を整理します。strictが無効だと`.optional()`や`.nullable()`の型推論が事実上無視される、という落とし穴も実例で確認します。

z.string()・z.number()・z.boolean()に用意されている検証メソッドを、引数と戻り値つきで整理します。メソッドをつなぐと新しいスキーマが返るという仕組みと、書く順番で結果が変わるケースも扱います。

Zodでスキーマを実行する4つのメソッドを整理します。parseは失敗時に例外を投げ、safeParseは結果オブジェクトを返します。どちらを使うべきかの判断基準と、戻り値を使わないと変換が反映されない落とし穴も扱います。

`z.string()` は空文字を通すのか、nullとundefinedはどちらが弾かれるのか。毎回迷うデフォルト挙動を、実際に動かした結果の早見表にまとめました。optional・nullable・nullish・default・catchの違いもここで整理します。

オブジェクトの検証をz.objectで書く方法を整理します。定義していないキーが黙って捨てられるデフォルト挙動、strictObjectとlooseObjectの使い分け、extendやpickでスキーマを組み立てる方法を扱います。

配列の要素をまとめて検証するz.array、位置ごとに型が違うz.tuple、キーが決まっていないオブジェクトを扱うz.recordの書き方を整理します。エラーがどの要素で起きたかを示すpathの読み方も扱います。

「AかBのどちらか」を表す4つの書き方を整理します。literalとenumで値を限定する方法、unionとdiscriminatedUnionの違い、そしてdiscriminatedUnionにするとエラーメッセージがどれだけ具体的になるかを実例で比べます。

「パスワードが一致しているか」のような、型だけでは表せない検証をrefineで書く方法と、検証しながら値を別の形に変える transform・pipe の使い方を整理します。エラーを特定の項目に紐づけるpathの指定も扱います。

スキーマからTypeScriptの型を取り出すz.infer・z.input・z.outputの使い分けを整理します。transformやdefaultを使うと入力型と出力型がずれる理由と、型を先に書くかスキーマを先に書くかの判断も扱います。

検証に失敗したときに返るZodErrorの構造と、issuesの読み方を整理します。項目ごとのメッセージに整形するtreeifyError・flattenError、日本語ロケールの適用方法、メッセージを自分で書く3つの方法を扱います。

HTMLフォームやURLクエリ、環境変数はすべて文字列で届きます。z.coerceで数値や真偽値に変換する方法と、空欄が0になる・"false"がtrueになるという2つの落とし穴、そして起動時に設定を検証するパターンを扱います。

React Hook FormのresolverにZodスキーマを渡して、入力検証とエラー表示を実装する方法を整理します。フォームの型にz.inputを使う理由、Server Actionと組み合わせるときのサーバー側検証も扱います。

Route Handlerでリクエストボディを検証する書き方と、fetchで受け取ったレスポンスを信用せずに検証する理由を整理します。検証をどの層に置くか、失敗したときにどう振る舞うかの設計も扱います。

ネットに残るZod 3の記事を読み解き、v4のコードに直すための対応表です。z.string().email()の非推奨化、required_errorが黙って無視される罠、エラー整形APIの変更、そして段階的に移行するためのzod/v3の使い方を扱います。

スキーマをどこに置き、どう共有するか。検証を重ねすぎない境界の決め方、他のバリデーションライブラリとの比較、Zodを使っていて実際に困る場面への対処をまとめます。

本書の内容を作業中に引ける形へ圧縮しました。スキーマ一覧、デフォルト挙動の早見表、メソッド一覧、エラー処理の定型、Zod 3からの対応表、そのままコピーして使えるスニペット集をまとめています。