Установка и первоначальная настройка

Библиотека Yup распространяется через экосистему Node.js и устанавливается стандартными менеджерами пакетов.

npm

npm install yup

yarn

yarn add yup

pnpm

pnpm add yup

После установки пакет становится доступным для импорта в проекте без дополнительных настроек сборщика в большинстве современных конфигураций (Vite, Webpack, Next.js, Rollup).

Подключение в проекте

Yup поддерживает как CommonJS, так и ES Modules, что делает интеграцию универсальной для разных типов проектов.

ES Modules

import * as yup from 'yup';

или точечный импорт отдельных функций:

import { object, string, number } from 'yup';

CommonJS

const yup = require('yup');

В большинстве современных фронтенд-проектов предпочтителен ESM-стиль, так как он лучше оптимизируется сборщиками и поддерживает tree-shaking.

Базовая структура схем

Основой работы Yup является создание схемы валидации. Схемы описывают структуру данных и правила проверки.

import * as yup from 'yup';

const schema = yup.object({
  name: yup.string().required(),
  age: yup.number().min(18).required(),
  email: yup.string().email().required()
});

Каждое поле схемы представляет собой цепочку методов-валидаторов, которые применяются последовательно.

Проверка данных

После создания схемы можно выполнить валидацию объекта.

Асинхронная валидация

schema.validate({
  name: 'Ivan',
  age: 25,
  email: 'ivan@example.com'
})
  .then(validData => {
    console.log(validData);
  })
  .catch(err => {
    console.log(err.errors);
  });

Синхронная валидация

try {
  const result = schema.validateSync({
    name: 'Ivan',
    age: 25,
    email: 'ivan@example.com'
  });
} catch (e) {
  console.log(e.errors);
}

Асинхронный режим используется по умолчанию и предпочтителен при работе с большими схемами или сложной логикой.

Параметры поведения валидации

Yup позволяет настраивать поведение проверки через опции метода validate.

schema.validate(data, {
  abortEarly: false,
  stripUnknown: true,
  strict: false
});

abortEarly

Определяет, останавливать ли проверку после первой ошибки.

  • true — остановка на первой ошибке
  • false — сбор всех ошибок

stripUnknown

Удаляет поля, не описанные в схеме.

  • полезно для очистки входных данных
  • часто используется в API-валидации

strict

Отключает приведение типов.

  • true — данные проверяются без преобразований
  • false — Yup пытается привести типы автоматически

Глобальная настройка сообщений об ошибках

Yup позволяет задавать пользовательские сообщения на уровне всей библиотеки.

import { setLocale } from 'yup';

setLocale({
  mixed: {
    required: 'Поле обязательно для заполнения'
  },
  string: {
    email: 'Некорректный email'
  },
  number: {
    min: 'Слишком маленькое значение'
  }
});

После вызова setLocale все схемы автоматически используют заданные сообщения, если не переопределены локально.

Использование с TypeScript

Yup поддерживает TypeScript «из коробки», включая вывод типов из схем.

import * as yup from 'yup';

const schema = yup.object({
  name: yup.string().required(),
  age: yup.number().required()
});

type User = yup.InferType<typeof schema>;

Тип User автоматически отражает структуру схемы.

Дополнительно можно явно типизировать результат:

const data: User = await schema.validate(input);

Импорт отдельных методов

Для уменьшения размера бандла можно импортировать только нужные части библиотеки.

import { object, string } from 'yup';

const schema = object({
  username: string().required()
});

Такой подход особенно важен в клиентских приложениях с ограничением по размеру JavaScript-бандла.

Использование в браузере без сборщика

Yup может подключаться напрямую через CDN.

<script src="https://cdn.jsdelivr.net/npm/yup@1.4.0/dist/yup.min.js"></script>
<script>
  const schema = yup.object({
    title: yup.string().required()
  });
</script>

В таком режиме библиотека доступна через глобальный объект yup.

Работа с импортами в различных средах

Разные окружения требуют корректного выбора формата подключения:

  • Node.js (CommonJS) — require
  • современный фронтенд — import
  • серверный TypeScript — ESM с типизацией
  • браузер без сборки — CDN

Некорректный выбор формата импорта может приводить к ошибкам вида undefined is not a function или проблемам с дефолтным экспортом.

Типовые проблемы при установке

В процессе интеграции Yup чаще всего возникают следующие ситуации:

Конфликт версий зависимостей

Некоторые старые проекты могут использовать несовместимые версии @types или TypeScript, что приводит к ошибкам типов.

Неправильный импорт

Использование:

import yup from 'yup';

вместо:

import * as yup from 'yup';

может привести к ошибкам при обращении к методам.

Отсутствие поддержки ESM

В старых версиях Node.js требуется включение "type": "module" или использование CommonJS.

Проблемы с tree-shaking

Импорт всей библиотеки целиком увеличивает размер бандла, если не используются точечные импорты.

Контекст выполнения и дополнительные настройки

Yup поддерживает передачу контекста валидации, что полезно для динамических правил.

schema.validate(data, {
  context: { role: 'admin' }
});

Контекст можно использовать внутри схем через функцию:

yup.string().test('check-role', function (value) {
  const { role } = this.options.context;
  return role === 'admin' ? true : value !== 'restricted';
});

Модификация поведения схем

Схемы можно переиспользовать и расширять без пересоздания.

const baseSchema = yup.object({
  id: yup.string().required()
});

const extendedSchema = baseSchema.shape({
  name: yup.string().required()
});

Метод shape позволяет добавлять новые поля, сохраняя базовую структуру.

Инициализация в прикладных сценариях

В реальных приложениях схема обычно создаётся отдельно от логики UI или API:

  • выделяется модуль схем
  • используется единая точка импорта
  • повторное использование между фронтендом и бэкендом
// validation/userSchema.js
import * as yup from 'yup';

export const userSchema = yup.object({
  username: yup.string().required(),
  password: yup.string().min(8).required()
});

Такая структура упрощает сопровождение и снижает дублирование правил валидации.

Оглавление