Yup - Quick Reference
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
npm install yup
Basic Usage
import * as yup from 'yup';
const userSchema = yup.object({
name: yup.string().required().min(2).max(50),
email: yup.string().required().email(),
age: yup.number().required().min(18).max(120).integer(),
bio: yup.string().optional(),
});
// Type inference
type User = yup.InferType<typeof userSchema>;
// Validate
async function validateUser(data: unknown) {
try {
const user = await userSchema.validate(data, { abortEarly: false });
return { success: true, data: user };
} catch (error) {
if (error instanceof yup.ValidationError) {
return { success: false, errors: error.errors };
}
throw error;
}
}
Schema Types
String
const stringSchema = yup
.string()
.required('Name is required')
.min(2, 'Too short')
.max(100, 'Too long')
.trim()
.email('Invalid email')
.url('Invalid URL')
.matches(/^[a-zA-Z]+$/, 'Only letters allowed')
.oneOf(['option1', 'option2'], 'Must be one of the options');
Number
const numberSchema = yup
.number()
.required()
.min(0)
.max(100)
.positive()
.integer()
.typeError('Must be a number');
Date
const dateSchema = yup
.date()
.required()
.min(new Date('2020-01-01'), 'Too old')
.max(new Date(), 'Cannot be in future');
Array
const arraySchema = yup
.array()
.of(yup.string().required())
.required()
.min(1, 'At least one item')
.max(10, 'Maximum 10 items')
.ensure(); // Transform null/undefined to []
Object
const objectSchema = yup.object({
name: yup.string().required(),
address: yup.object({
street: yup.string().required(),
city: yup.string().required(),
}),
}).noUnknown(true); // Strip unknown keys
// Partial object (all fields optional)
const partialSchema = objectSchema.partial();
Validation Options
const result = await schema.validate(data, {
abortEarly: false, // Return all errors, not just first
stripUnknown: true, // Remove unknown keys
strict: false, // Allow type coercion
});
// Sync validation
schema.validateSync(data);
schema.isValidSync(data); // Returns boolean
Comparison: Yup vs Zod
| Feature | Yup | Zod |
|---|
| Type inference | Good | Excellent |
| Bundle size | ~12KB | ~8KB |
| Async validation | Built-in | .parseAsync() |
| Formik | Native | Via resolver |
| Conditional | .when() | .refine() |
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
| Anti-Pattern | Why It's Bad | Correct Approach |
|---|
| Schema in component | Re-created on render | Define at module level |
| Forgetting abortEarly: false | Only shows first error | Set abortEarly: false |
| No custom messages | Generic errors | Add custom message to each |
| Not using InferType | Manual type definitions | Use yup.InferType |
Quick Troubleshooting
| Issue | Cause | Solution |
|---|
| Type errors with InferType | Missing import | Import type from 'yup' |
| Async validation not working | Using validateSync | Use.validate() (async) |
| "Value is required" unexpectedly | Undefined vs null | Use.nullable() or.optional() |
| Error messages not showing | abortEarly: true | Set abortEarly: false |
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
