Установка через npm и yarn

Пакет class-validator распространяется как стандартный npm-модуль и устанавливается в проект через менеджер пакетов Node.js. Базовая команда установки добавляет библиотеку в зависимости проекта:

npm install class-validator

После установки пакет появляется в node_modules, а запись о зависимости фиксируется в package.json. В большинстве современных проектов на TypeScript библиотека используется совместно с class-transformer, поскольку обе библиотеки ориентированы на работу с классами и метаданными.

Типичная установка набора зависимостей для экосистемы валидации выглядит следующим образом:

npm install class-validator class-transformer

Дополнительно в проектах, использующих TypeScript, требуется включение поддержки декораторов и метаданных. Это связано с тем, что class-validator опирается на отражение типов во время выполнения.

Настройка TypeScript для работы с декораторами

Для корректной работы библиотеки необходимо включить параметры компилятора TypeScript:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Параметр experimentalDecorators активирует поддержку декораторов, а emitDecoratorMetadata обеспечивает генерацию метаданных типов, которые используются валидаторами для определения структуры данных.

Также требуется подключение полифила отражения метаданных:

npm install reflect-metadata

И последующий импорт в точке входа приложения:

import "reflect-metadata";

Без этого механизма часть валидаторов, зависящих от типов свойств, будет работать некорректно или не будет работать вовсе.

Установка в проектах Node.js без TypeScript

Несмотря на то, что основное применение библиотеки связано с TypeScript, она может использоваться и в JavaScript-проектах при условии ручного описания ограничений или использования совместимых подходов. Установка остаётся идентичной:

npm install class-validator

Однако отсутствие метаданных типов накладывает ограничения на автоматическое определение типов значений. В таких случаях валидация строится на явных правилах, задаваемых через декораторы или функции.

Установка через yarn

В экосистеме Yarn установка выполняется аналогично npm, с использованием команды добавления пакета:

yarn add class-validator

Для совместного использования с трансформацией объектов добавляется второй пакет:

yarn add class-validator class-transformer

При использовании Yarn 2+ и Yarn Berry структура установки не меняется, однако управление зависимостями осуществляется через Plug’n’Play или через node_modules в зависимости от конфигурации проекта.

Установка вспомогательных зависимостей

Для проектов на TypeScript с декораторами требуется установка reflect-metadata:

yarn add reflect-metadata

Далее импорт библиотеки осуществляется аналогично npm-проектам:

import "reflect-metadata";

Совместимость версий Node.js и TypeScript

Библиотека ориентирована на современные версии Node.js. В типичных конфигурациях используется Node.js версии 14 и выше, однако оптимальной считается актуальная LTS-ветка.

TypeScript рекомендуется версии 4.x и выше, поскольку поддержка декораторов и метаданных в более ранних версиях отличается по поведению и может приводить к несовместимости типов.

Структура зависимостей и роль reflect-metadata

Механизм работы class-validator основан на анализе метаданных, прикреплённых к свойствам классов. Эти метаданные генерируются TypeScript при компиляции и считываются во время выполнения через reflect-metadata.

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

  • TypeScript компилирует классы и декораторы
  • reflect-metadata сохраняет информацию о типах
  • class-validator читает метаданные и применяет правила валидации

Без установки и подключения reflect-metadata часть встроенных валидаторов теряет возможность определять типы значений автоматически.

Проверка корректности установки

После установки библиотека импортируется в модуль без дополнительных настроек сборщика:

import { validate } from "class-validator";

Если импорт выполняется без ошибок, а зависимости корректно установлены, библиотека готова к использованию в рамках проектной конфигурации.

Установка в монорепозиториях

В монорепозиториях (например, с использованием Turborepo или Nx) установка выполняется на уровне корневого workspace:

npm install class-validator

или

yarn add class-validator

При использовании workspace-режима важно учитывать, что reflect-metadata должен быть доступен в том пакете, где выполняется инициализация приложения, иначе метаданные не будут подхвачены рантаймом.

Особенности установки в фронтенд-проектах

В клиентских приложениях на базе React, Vue или Angular библиотека также устанавливается стандартной командой менеджера пакетов. Однако следует учитывать, что часть функционала опирается на runtime-рефлексию, что влияет на размер бандла и требования к транспиляции.

Типичная установка:

npm install class-validator

или

yarn add class-validator

В Angular-проектах поддержка декораторов уже встроена в стандартную конфигурацию TypeScript, поэтому дополнительная настройка обычно ограничивается подключением reflect-metadata.

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

После установки пакета и сопутствующих зависимостей точка входа приложения должна содержать первичную инициализацию метаданных:

import "reflect-metadata";

Далее подключаются модули, использующие декораторы валидации:

import { IsString, IsInt } from "class-validator";

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

Частые конфигурационные ошибки при установке

Некорректная работа библиотеки чаще всего связана не с самой установкой, а с конфигурацией окружения:

  • отключён emitDecoratorMetadata
  • не подключён reflect-metadata
  • используется несовместимая версия TypeScript
  • отсутствует поддержка декораторов в сборщике
  • пакет установлен в неправильный workspace

Такие проблемы проявляются в виде отсутствия валидации или потери типизации на этапе выполнения.

Установка в средах CI/CD

В автоматизированных окружениях установка выполняется стандартными командами npm ci или yarn install:

npm ci

или

yarn install --frozen-lockfile

Использование ci-режима обеспечивает повторяемость установки зависимостей и исключает расхождения версий между локальной и серверной средой.

Роль peer dependencies

class-validator использует некоторые зависимости косвенно через механизмы TypeScript и reflect API, но не требует жёсткой фиксации peer dependencies в большинстве конфигураций. Однако при интеграции с фреймворками (например, NestJS) важно учитывать совместимость версий, поскольку фреймворк может задавать ограничения на версии class-validator.

Итоговая структура установленного окружения

После установки в типичном TypeScript-проекте формируется следующий набор компонентов:

  • class-validator — механизм декларативной валидации
  • class-transformer — преобразование объектов
  • reflect-metadata — слой метаданных выполнения
  • TypeScript с включёнными декораторами

Такая связка формирует основу для дальнейшего описания правил валидации через классы и декораторы без необходимости ручной проверки структур данных.

Оглавление