TypeScriptだけでは不十分：Next.jsでZodを使ったエンドツーエンドの型安全性

型安全性の幻想

TypeScriptは、現代のJavaScriptアプリケーションの救世主としてしばしば語られます。タイポを検出し、オブジェクトプロパティを自動補完し、開発中の未定義関数の呼び出しを防ぎます。

しかし、厳格なTypeScriptコンパイラ設定を有効にしているにもかかわらず、毎日何百もの本番Next.jsおよびNode.jsアプリケーションが、TypeError: Cannot read properties of undefined (reading 'map')やTypeError: data.slice is not a functionといったエラーでクラッシュしています。

なぜこのようなことが起こるのでしょうか？

それは、TypeScriptがランタイムに存在しないからです。コードがコンパイルされると、すべてのインターフェース、型エイリアス、ジェネリックパラメータ、および型アサーション（as User）はJavaScriptバンドルから消去されます。ネットワーク境界（受信HTTPリクエスト、Next.jsサーバーアクションのペイロード、サードパーティのWebhookイベント、データベースクエリ結果）では、コードを流れるデータは完全に型付けされていません。

真のエンドツーエンドの信頼性を実現するには、システムにデータが入力されるときにデータを検証する必要があります。そこでZodが不可欠になります。

生のAPI JSONをTypeScriptインターフェースとZodスキーマに即座に変換する必要がありますか？当社のコンパニオンツール JSON to TypeScript & Zod Generator Tool をご利用ください。

静的型とランタイムスキーマ

TypeScriptインターフェースとZodスキーマの根本的な違いを理解することが、堅牢なアーキテクチャを構築するための鍵です。

脆弱なサーバーアクションをZodにリファクタリングする

開発者がランタイム検証なしに型アサーションを使用する、Next.jsサーバーアクションの一般的な脆弱性を見てみましょう。

Zodの高度な使用法のための4つの強力なテクニック

1. フォームデータとURL検索パラメータのためのz.coerce

HTML FormDataまたはNext.js searchParamsをパースする場合、すべてが文字列として到着します（"42"、"true"）。手動でparseInt()やBoolean()を記述する代わりに：

const FilterSchema = z.object({
  page: z.coerce.number().default(1),
  limit: z.coerce.number().default(20),
  active: z.coerce.boolean().default(true),
});

2. safeParse vs parse

• schema.parse(data)は検証に失敗した場合、ZodErrorをスローします。これは、try/catchブロック内、またはグローバルエラーミドルウェアを持つトップレベルのAPIハンドラー内でのみ使用してください。
• schema.safeParse(data)は決してスローしません。これは判別共用体（discriminated union）を返します：{ success: true, data }または{ success: false, error }。これはNext.jsサーバーアクションやReact Hook Formに最適です。

3. スキーマの構成と継承

Zodスキーマは構成可能です。拡張、マージ、フィールドの選択ができます。

const BaseUserSchema = z.object({
  id: z.string().uuid(),
  createdAt: z.date(),
});

const UpdateProfileSchema = BaseUserSchema.extend({
  bio: z.string().max(500).optional(),
  displayName: z.string().min(2),
});

4. .refine()によるカスタムリファインメント

クロスフィールド検証（例：「確認パスワード」が「パスワード」と一致することを確認する）の場合：

const PasswordChangeSchema = z.object({
  newPassword: z.string().min(8),
  confirmPassword: z.string().min(8),
}).refine((data) => data.newPassword === data.confirmPassword, {
  message: "Passwords do not match",
  path: ["confirmPassword"],
});

インタラクティブクイズ：Zodの知識を試す

こちらもおすすめ

• Next.js Middleware:堅牢な認証と認可の構築
• Next.jsとWebGLの統合：包括的なガイド
• Next.js、Contentlayer、Git Submodulesでポートフォリオを構築した方法
• 忘れがちなことを記録するTILマイクロブログの作り方

よくある質問