Начало работы с Valibot

TypeScript обеспечивает безопасность типов на этапе компиляции, но не может защитить вас во время выполнения. Когда данные поступают из отправленной формы, ответа API или файла конфигурации, типы TypeScript уже отсутствуют. Именно этот пробел заполняют библиотеки валидации схем — и именно здесь Valibot проявляет себя наилучшим образом.

Это руководство познакомит вас с тем, что такое Valibot, как он работает и как начать использовать его для валидации схем TypeScript в реальных frontend-проектах.

Что такое Valibot и зачем его использовать?

Valibot — это модульная библиотека валидации схем, ориентированная на TypeScript. Она проверяет неизвестные данные во время выполнения и выводит статические типы TypeScript из ваших схем, поэтому ваша схема становится единственным источником истины как для безопасности во время выполнения, так и для типов на этапе компиляции.

Её отличительной особенностью является архитектура. Вместо одного большого объекта с цепочкой методов (подход, который использует Zod), Valibot построен из множества небольших независимых функций. Сборщики могут исключить всё, что вы не используете (tree-shake), что позволяет сохранить минимальный размер production-бандла — часто около ~1 КБ в зависимости от использования. Это существенное преимущество для frontend-приложений, где размер бандла напрямую влияет на время загрузки.

Valibot стабилен, активно поддерживается и имеет версию v1+, что делает его надёжным выбором для production-использования.

Определение первой схемы Valibot

Определение схемы в Valibot выглядит похоже на написание типа TypeScript, но выполняется во время выполнения:

import * as v from 'valibot'

const LoginSchema = v.object({
  email: v.string(),
  password: v.string(),
})

Затем вы можете вывести тип TypeScript непосредственно из схемы:

type LoginData = v.InferOutput<typeof LoginSchema>
// { email: string; password: string }

Никакого дублирования. Ваша схема и ваш тип автоматически остаются синхронизированными.

Парсинг и валидация данных

Valibot предоставляет два основных способа валидации данных.

parse выбрасывает ошибку при неудачной валидации:

const data = v.parse(LoginSchema, { email: 'jane@example.com', password: '12345678' })

safeParse возвращает объект результата вместо выброса исключения, что полезно, когда вы хотите обрабатывать ошибки без try/catch:

const result = v.safeParse(LoginSchema, { email: '', password: '' })

if (!result.success) {
  console.log(result.issues) // Структурированные детали ошибок
}

Для валидации форм safeParse обычно является лучшим выбором — он делает обработку ошибок чистой и предсказуемой.

Композируемые конвейеры валидации

Функция pipe в Valibot позволяет объединять в цепочку шаги валидации и преобразования. Конвейер всегда начинается с базовой схемы, за которой следуют действия, выполняемые последовательно:

const EmailSchema = v.pipe(
  v.string('Email must be a string.'),
  v.nonEmpty('Please enter your email.'),
  v.email('Invalid email format.')
)

Каждое действие получает выход предыдущего. Это упрощает применение правил, таких как минимальная длина, определённые форматы или пользовательские ограничения — всё с понятными сообщениями об ошибках на уровне полей, которые вы контролируете.

Valibot vs Zod: ключевое отличие

Обе библиотеки решают одну и ту же основную проблему. Практическое различие заключается в философии дизайна и влиянии на размер бандла.

Если вы уже используете Zod, миграция проста — концепции тесно связаны, и документация Valibot включает руководство для разработчиков, выполняющих переход.

Экосистема и что дальше

Valibot хорошо интегрируется с популярными библиотеками форм. Библиотека Superforms для SvelteKit имеет первоклассную поддержку Valibot, и существуют адаптеры для React Hook Form и других инструментов.

Для команд, которым необходим вывод JSON Schema — для документации API или спецификаций OpenAPI — отдельный пакет @valibot/to-json-schema справляется с этой задачей. Интернационализация сообщений об ошибках также поддерживается через @valibot/i18n, что делает Valibot практичным для многоязычных приложений.

Заключение

Valibot обеспечивает безопасность типов во время выполнения, чистый вывод типов TypeScript и минимальный размер — без накладных расходов более тяжёлых альтернатив. Установите его, определите схему и позвольте вашей логике валидации стать основой, на которой строятся ваши типы.

npm install valibot

С этого момента ваши схемы могут расти вместе с вашим приложением — от простых проверок строк до сложных вложенных объектов — не раздувая при этом ваш бандл.

Часто задаваемые вопросы

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.