Zod Compiler: валидация на этапе сборки
в 2–75 раз быстрее

Что такое zod-compiler?

zod-compiler — это плагин времени сборки от Гайюса Куизинаса (автора Slonik и многих других TypeScript-инструментов), который компилирует схемы Zod в оптимизированные валидаторы. Он работает с Vite, webpack, esbuild, Rollup, Rolldown, rspack, Bun и Farm — то есть с любым современным сборщиком.

Ключевая идея в том, что runtime-валидация Zod обходит дерево схемы при каждом вызове: для каждого z.string(), z.object() и z.union() Zod проходит по внутреннему представлению и проверяет типы узел за узлом. Скомпилированный валидатор сворачивает этот обход в единственное булево выражение — или switch-диспетчеризацию для объединений — устраняя все накладные расходы на обход узлов.

Версия 1.13.1 опубликована в npm 17 июня 2026 года, проект набрал более 322 звёзд на GitHub и активно развивается. Протестирован в продакшен-проектах с десятками тысяч схем Zod.

Установка и настройка

1. Установка пакета

npm install --save-dev zod-compiler
# или
pnpm add -D zod-compiler
# или
yarn add -D zod-compiler

2. Подключение плагина

Для Vite (самый распространённый вариант):

// vite.config.ts
import { defineConfig } from "vite";
import zodCompiler from "zod-compiler/vite";

export default defineConfig({
  plugins: [zodCompiler()],
});

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

3. Готово

В автоматическом режиме (по умолчанию) плагин сканирует все файлы, импортирующие из "zod", находит экспортированные схемы Zod и компилирует их на этапе сборки. Ваши файлы со схемами остаются чистым Zod:

// src/schemas/user.ts — без изменений, чистый Zod
import { z } from "zod";

export const CreateUserSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.email(),
  age: z.number().int().min(0).max(150),
  role: z.enum(["admin", "editor", "viewer"]),
});

export const UpdateUserSchema = z.object({
  name: z.string().min(1).max(100).optional(),
  email: z.email().optional(),
});

Код использования тоже остаётся прежним:

import { CreateUserSchema } from "./schemas/user";

const user = CreateUserSchema.parse(data);  // компилируется в оптимизированный валидатор
const result = CreateUserSchema.safeParse(data);  // { success, data/error }

Три способа использования

Автоматический режим (рекомендуется)

Как показано выше: добавьте плагин, и каждая экспортированная схема Zod в проекте скомпилируется автоматически. Статический предфильтр пропускает файлы, чьи экспорты заведомо не могут быть схемами (функции, компоненты, константы), без их выполнения.

Автоматический режим также включает поднятие схем (schema hoisting) — схемы, определённые внутри функций (компоненты React, обработчики запросов, хелперы), перемещаются на уровень модуля:

// До: схема пересоздаётся при каждом вызове
function getSchema() {
  return z.object({ name: z.string() });
}

// После (результат сборки): схема создаётся один раз при загрузке модуля
const _zh_schema = z.object({ name: z.string() });
function getSchema() {
  return _zh_schema;
}

Это значит, что схема внутри React-компонента, проверяющая пропсы, или внутри обработчика запроса, создаётся один раз при загрузке модуля, а не при каждом вызове. Компилятор также дедуплицирует идентичные схемы в единую привязку.

Явный режим с compile()

Если вы предпочитаете явное включение, оберните отдельные схемы в compile():

import { z } from "zod";
import { compile } from "zod-compiler";

const UserSchema = z.object({
  name: z.string().min(3),
  email: z.email(),
});

export const validateUser = compile(UserSchema);

// В dev: использует runtime Zod
// После сборки: AOT-скомпилированный валидатор
validateUser.parse(data);

В паре с schemas: "explicit" в опциях плагина compile() становится единственным путём компиляции — автоматическое сканирование отключается. Это идеально для постепенного внедрения в больших кодовых базах.

CLI-режим (без сборщика)

Для проектов без сборщика или для разовой компиляции:

# Один файл
npx zod-compiler generate src/schemas.ts -o src/schemas.compiled.ts

# Директория
npx zod-compiler generate src/ -o src/compiled/

# Режим отслеживания
npx zod-compiler generate src/ --watch

# Удаление неизвестных ключей из вывода z.object()
npx zod-compiler generate src/ --strip-unknown-keys

Сравнение производительности

Бенчмарк сравнивает zod-compiler с Zod v3, Zod v4, Typia и AJV. Результаты в ops/s (выше — лучше), измерено на Apple M4 Max.

Наибольший прирост дают вложенные объекты, большие схемы и некорректные данные (где Zod строит дорогие объекты ошибок, а скомпилированный валидатор откладывает материализацию ошибок). Случай с невалидным объектом достигает 194x, потому что быстрый путь отклоняет некорректный ввод одной булевой проверкой — дорогое дерево ошибок никогда не создаётся.

Архитектура производительности

zod-compiler использует двухфазный валидатор:

1. Быстрый путь — цепочка булевых выражений через &&, проверяющая весь ввод с нулевым выделением памяти. Корректный ввод возвращается мгновенно.
2. Медленный путь — валидация со сбором ошибок, запускается только если быстрый путь не прошёл. Объект ошибки строится лениво — при обращении к .error.

Дополнительные оптимизации: порядок проверок (сначала дешёвые), предварительно скомпилированные регулярные выражения, Set-поиск для enum, инлайнинг маленьких enum (≤5 значений через ===), O(1) switch-диспетчеризация для discriminated unions и автоопределение обычных z.union размеченных объектов.

Типовой охранник .is()

Скомпилированные схемы предоставляют дополнительный метод: .is(input): input is T. Для большинства схем (объекты, примитивы, массивы, enum без coerce, default, catch или transform) это самая дешёвая проверка «совпадает ли?»:

// Вместо safeParse().success:
if (UserSchema.is(data)) {
  data.email; // сужение до типа вывода схемы
}

// Фильтрация невалидных элементов:
const valid = items.filter((x) => UserSchema.is(x));

Охранник .is() возвращает булево значение без единого выделения памяти — никакого SafeParseResult, никакого массива ошибок, никакого дерева. Он сопоставим с Typia is<T>() и является чистой заменой schema.safeParse(x).success.

Размер бандла и tree-shaking

zod-compiler спроектирован для минимального влияния на размер бандла:

• Общий runtime — все скомпилированные валидаторы импортируют хелперы из единого runtime-модуля, который добавляется в бандл ровно один раз.
• Дедупликация между файлами — общие регулярные выражения для email, uuid, ipv4 и т.д. появляются один раз во всём бандле.
• Структурная дедупликация — идентичные подсхемы (например, переиспользуемый Address или Money) разделяют общую функцию сбора ошибок.
• Режим bag — установите output: "bag" чтобы убрать ссылку на оригинальную схему Zod, если вам не нужен instanceof или .shape.

Совместимость и интеграция

Скомпилированная схема сохраняет полную совместимость с API Zod. Оптимизированные методы parse/safeParse/parseAsync/ safeParseAsync устанавливаются непосредственно на исходный объект схемы:

• ._zod — без изменений
• .shape — без изменений
• Standard Schema (~standard) — без изменений
• instanceof — работает
• .meta() / z.globalRegistry — работают
• z.toJSONSchema() — работает

Библиотеки, принимающие схемы Zod, работают без изменений:

• tRPC — входные данные процедур компилируются автоматически
• Hono — middleware валидации на Zod использует скомпилированные схемы
• React Hook Form — zodResolver использует скомпилированный .parse

Практические соображения

Побочные эффекты в файлах схем

В автоматическом режиме плагин выполняет файлы для проверки экспортов. Если файл схемы имеет побочные эффекты (запускает сервер, подключается к БД), они выполнятся на этапе сборки. zod-compiler защищает от этого:

• Устанавливает process.env.ZOD_COMPILER для оповещения модулей
• Перехватывает process.exit — выход превращается в обычную ошибку загрузки, сборка не ломается

Простейший способ избежать проблем — использовать include:

zodCompiler({
  include: ["src/schemas", "src/validators"],
});

Интеграция с CI

zod-compiler имеет постоянный кэш трансформаций в node_modules/.cache/zod-compiler. Записи кэша самопроверяются по хешам содержимого зависимостей — восстановление устаревшего кэша вызывает перекомпиляцию, но никогда не выдаёт устаревший вывод:

- uses: actions/cache@v4
  with:
    path: node_modules/.cache/zod-compiler
    key: zod-compiler-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}

Постепенное внедрение

Для больших существующих кодовых баз начните с schemas: "explicit" и оберните только самые горячие пути — схемы, валидируемые чаще всего или на самых больших объёмах данных. Валидация API-запросов, проверка строк БД и обработчики форм — цели с наибольшим эффектом.

FAQ

Заключение

zod-compiler — один из тех редких инструментов, который даёт драматический прирост производительности с нулевыми усилиями разработчика. Установите плагин, оставьте все существующие схемы Zod, и ваша валидация станет в 2–75 раз быстрее. Никаких изменений API, никакой миграции, никаких runtime-зависимостей.

Двухфазная архитектура — быстрый путь для корректных данных, ленивая материализация ошибок для невалидных — означает, что типичный случай (большинство данных проходит валидацию) работает так же быстро, как ручной типовой охранник. А функция поднятия схем устраняет целый класс багов производительности, когда схемы пересоздаются при каждом рендере React или каждом вызове обработчика.

Если ваш проект использует Zod — попробуйте zod-compiler. Запустите pnpm benchmark локально, чтобы увидеть улучшение на вашем железе. Цифры говорят сами за себя.