Full Reference: See advanced.md for conditional validation (.when), custom validation (.test), Formik/React Hook Form integration, transforms, and localization.

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: yup for comprehensive documentation.

Setup

bash
1npm install yup

Basic Usage

typescript
1import * as yup from 'yup';
2
3const userSchema = yup.object({
4  name: yup.string().required().min(2).max(50),
5  email: yup.string().required().email(),
6  age: yup.number().required().min(18).max(120).integer(),
7  bio: yup.string().optional(),
8});
9
10// Type inference
11type User = yup.InferType<typeof userSchema>;
12
13// Validate
14async function validateUser(data: unknown) {
15  try {
16    const user = await userSchema.validate(data, { abortEarly: false });
17    return { success: true, data: user };
18  } catch (error) {
19    if (error instanceof yup.ValidationError) {
20      return { success: false, errors: error.errors };
21    }
22    throw error;
23  }
24}

Schema Types

String

typescript
1const stringSchema = yup
2  .string()
3  .required('Name is required')
4  .min(2, 'Too short')
5  .max(100, 'Too long')
6  .trim()
7  .email('Invalid email')
8  .url('Invalid URL')
9  .matches(/^[a-zA-Z]+$/, 'Only letters allowed')
10  .oneOf(['option1', 'option2'], 'Must be one of the options');

Number

typescript
1const numberSchema = yup
2  .number()
3  .required()
4  .min(0)
5  .max(100)
6  .positive()
7  .integer()
8  .typeError('Must be a number');

Date

typescript
1const dateSchema = yup
2  .date()
3  .required()
4  .min(new Date('2020-01-01'), 'Too old')
5  .max(new Date(), 'Cannot be in future');

Array

typescript
1const arraySchema = yup
2  .array()
3  .of(yup.string().required())
4  .required()
5  .min(1, 'At least one item')
6  .max(10, 'Maximum 10 items')
7  .ensure();  // Transform null/undefined to []

Object

typescript
1const objectSchema = yup.object({
2  name: yup.string().required(),
3  address: yup.object({
4    street: yup.string().required(),
5    city: yup.string().required(),
6  }),
7}).noUnknown(true);  // Strip unknown keys
8
9// Partial object (all fields optional)
10const partialSchema = objectSchema.partial();

Validation Options

typescript
1const result = await schema.validate(data, {
2  abortEarly: false,    // Return all errors, not just first
3  stripUnknown: true,   // Remove unknown keys
4  strict: false,        // Allow type coercion
5});
6
7// Sync validation
8schema.validateSync(data);
9schema.isValidSync(data);  // Returns boolean

Comparison: Yup vs Zod

When NOT to Use This Skill

• New projects - Prefer Zod for better TypeScript integration
• NestJS applications - Use class-validator with decorators
• Non-form validation - Zod has better API for general validation

Anti-Patterns

Quick Troubleshooting

Production Checklist

• Schema defined at module level
• Type inference with InferType
• Custom error messages
• abortEarly: false for forms
• Resolver for form library
• Localization if multilingual

Reference Documentation

• Yup GitHub