JavaScriptバリデーションライブラリ Yup 入門ガイド

この記事の最終更新日: 2025年6月23日

はじめに

入力バリデーションはフロントエンド・バックエンドを問わず欠かせない安全装置です。Yup は JavaScript／TypeScript で手軽に 宣言的スキーマバリデーション を行えるライブラリとして広く使われています。この記事では、初心者の方にもわかりやすいように 基本から応用まで を丁寧に解説します。

バリデーションとは？：ユーザーが入力した内容が正しいかどうかを確認する仕組みのことです。例えば、年齢に文字が入っていないか、メールアドレスの形式が正しいかをチェックします。

1. Yup とは？

宣言的 にスキーマ（型 + 制約）を記述し、データを検証するライブラリ。
Formik、React-Hook-Form、Next.js のサーバーアクションなどと組み合わせて使われることが多い。
バリデーション結果は 同期／非同期 の両方で取得可能。

スキーマとは？：データがどのような形式（型）や条件（制約）であるべきかを定義するものです。例えば「名前は必須で文字列、年齢は0歳以上の数値」といったルールの集合です。

同期／非同期とは？：同期はその場ですぐに結果を返す処理、非同期は時間がかかる処理（例えばネットワーク通信など）を別スレッドで行い、後で結果を受け取る処理です。

2. Yup を選ぶ理由

理由	詳細
シンプルな API	`yup.string().required()` のように直感的に書ける
TypeScript との相性	`infer` 型サポートで型安全に扱える
チェーン記法	制約をドットチェーンで積み重ねられるので読みやすい
国際化対応	エラーメッセージを簡単にローカライズ可能
豊富な拡張	`addMethod` でカスタムルールを追加できる

TypeScriptとは？：JavaScriptを拡張して型チェックを可能にしたプログラミング言語です。

型安全とは？：変数や関数に設定したデータ型を厳密に守ることで、バグの発生を減らす仕組みです。

3. インストールとセットアップ

# npm
npm install yup
# または yarn / pnpm

TypeScript プロジェクトの場合、型定義は同梱されているため追加は不要です。

npm/yarn/pnpm：JavaScriptのライブラリを管理・インストールするためのツールです。

4. 基本のスキーマ定義

4.1 文字列

import * as yup from "yup";

const schema = yup.string().required().min(3).max(30);

min(3)は「3文字以上」、max(30)は「30文字以下」の意味です。

4.2 数値

const numSchema = yup.number().integer().positive();

integer()は「整数であること」、positive()は「0より大きいこと」を意味します。

4.3 メールアドレス

const emailSchema = yup.string().email("メールアドレスの形式が正しくありません");

4.4 オブジェクト

const userSchema = yup.object({
  name: yup.string().required(),
  age: yup.number().min(0).max(130).required(),
  email: emailSchema,
});

オブジェクトスキーマは複数のフィールド（項目）をまとめて定義できます。

5. バリデーションの実行方法

5.1 同期的に検証

try {
  userSchema.validateSync(data);
  // OK 時のロジック
} catch (e) {
  // e.errors は配列
}

validateSync()はその場で結果を返します。try...catchでエラーを受け取れます。

5.2 非同期で検証

await userSchema.validate(data, { abortEarly: false }); // すべてのエラーを取得

abortEarly: falseを指定すると、1つのエラーで止まらず、全てのエラーを確認できます。

6. React との統合例

6.1 React-Hook-Form

import { useForm } from "react-hook-form";
import { yupResolver } from "@hookform/resolvers/yup";

const { register, handleSubmit, formState: { errors } } = useForm({
  resolver: yupResolver(userSchema),
});

resolverを使うことで Yup のバリデーションルールを React のフォームに統合できます。

6.2 Formik

<Formik
  initialValues={{ name: "", age: "", email: "" }}
  validationSchema={userSchema}
  onSubmit={handleSubmit}
>
  {/* ... */}
</Formik>

Formikはフォームの状態管理とバリデーションを助けてくれるライブラリです。

7. カスタムバリデーションとメッセージ

yup.addMethod(yup.string, "katakana", function (msg) {
  return this.matches(/^[ァ-ヶー\s]+$/, {
    message: msg ?? "全角カタカナで入力してください",
    excludeEmptyString: true,
  });
});

const schema = yup.string().katakana();

addMethod を使うと独自ルール（例：カタカナだけ）を定義できます。

8. スキーマの再利用と DRY 原則

複数画面で同じスキーマを使う場合は 関数に切り出す か、schemas/ ディレクトリに共通定義を置くと管理しやすくなります。

DRY原則とは？：「Don’t Repeat Yourself（繰り返すな）」の略で、同じ処理や定義を何度も書かない設計方針です。

9. よくあるエラーとデバッグ Tips

エラー	原因	対処
`ValidationError: data must be a`	型が合わない	スキーマと入力データを再確認
期待したエラーが出ない	`abortEarly` が true	`validate({ abortEarly:false })` に設定
オブジェクトのネストでキーが undefined	スキーマが部分一致を許可	`.defined()` を付与

デバッグ：バグやエラーの原因を見つけて修正する作業のことです。

10. まとめ

Yup は 書き味と拡張性のバランスが取れた バリデーションライブラリです。この記事で紹介した基礎を押さえておけば、ほとんどのフォーム検証はスムーズに実装できます。フォーム処理に悩んだら、まず Yup を試してみましょう。

FAQ

Q. Joi や Zod と比べてどう？

Joi: Node.js サーバー向け。重量級だが高機能。
Zod: TypeScript ファーストで型推論が強力。
Yup: フロントエンドでの利用例が豊富。軽量で学習コストが低い。

Q. ブラウザ対応は？

ES2015+ をサポートするモダンブラウザなら問題なし。

ES2015+：2015年以降の新しいJavaScriptの書き方を指します（例：アロー関数、クラス構文など）。

11. 最新アップデート（2024–2025）備考

バージョン	公開日	主要変更点（抜粋）
1.6.1	2024‑12‑17	Bug Fix: `lazy()` のバリデーションエラーが他の非同期バリデーションと同じ挙動で解決されるように修正
1.6.0	2024‑12‑16	新機能: `LazySchema` を公開し、遅延スキーマ構築が公式 API に
1.5.0	2024‑12‑03	新機能: `object()` に `exact()` と `stripUnknown()` を追加し、オブジェクトキーの厳密制御が可能に
1.4.0	2024‑03‑06	新機能: `string().datetime()` を追加（ISO 8601 / RFC 3339 形式の日時文字列を検証）
1.3.x 系	2023‑09〜12	スキーマメタデータの型安全化・パフォーマンス改善など