Compile Zod schemas into zero-overhead validation functions at build time.
Keep your existing Zod schemas. Get up to 43x faster validation, and up to 140x on rejected
input. No code changes required.
Requires Zod ≥ 4.5; compiled output reproduces 4.5's semantics exactly, so it does not match
earlier 4.x releases. Use zod-compiler 1.x for Zod 4.0–4.4. An older Zod is refused with an explicit
error; the build plugin and jit() warn once and leave schemas as plain Zod.
Classic zod and zod/mini schemas compile alike, and compile() and jit() accept both. A compiled
schema fails the way its flavor does: classic schemas with ZodError, Mini schemas with Zod core's
$ZodError.
[!NOTE]
zod-compiler has been tested to work in large projects with tens of thousands of Zod schemas.
z.compile vs zod-compiler
Both generate optimized JavaScript. Zod's does it at runtime
with (JIT); zod-compiler's plugins and CLI do it at build time (AOT), so production
loads pre-generated validators.
The plugin detects and compiles every exported Zod schema at build time. No wrappers, no imports from zod-compiler in your source.
vite.config.ts:
import zodCompiler from "zod-compiler/vite";export default defineConfig({ plugins: [zodCompiler()],});
Your schema file stays pure Zod:
// src/schemas.tsimport { z } from "zod";export const CreateUserSchema = z.object({ name: z.string().min(1).max(100), email: z.email(), role: z.enum(["admin", "editor", "viewer"]),});
Use them as usual. Methods are installed on the original schema object, so .shape, ._zod, Standard
Schema, instanceof and z.toJSONSchema() keep working.
Compiled schemas also expose .is(input): input is T, a zero-allocation drop-in for
safeParse(x).success.
2. compile() (Explicit)
If you prefer explicit opt-in, wrap specific schemas with 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);// In dev: falls back to Zod's runtime validation// After build: uses AOT-compiled optimized codevalidateUser.parse(data);validateUser.safeParse(data);
compile() and auto mode coexist. Pair with schemas: "explicit" to make compile() the only path:
no automatic detection, no build-time execution of plain schema files.
3. CLI (No Bundler)
Generate optimized validation files from the command line:
Same validators a build emits, installed on the schema object, so Zod interop is unchanged.
Compilation is lazy, costing 0.1-0.3 ms on a schema's first parse. { eager: true } compiles up front
and jitAll(namespace) takes a whole module.
The cost is the import: ~570 KB of codegen and acorn, ~10 ms of module load. That suits a
long-lived process, not a CLI, a cold serverless handler or a browser.
Needs new Function, as Zod's own object fast-path does. z.config({ jitless: true }) and a CSP
that blocks eval both leave a working plain-Zod schema.
5. Node.js Register Hook
Node.js 22.15+ can automatically insert the equivalent of jit() for exported schemas as modules
load, with no source changes and no bundler:
node --import zod-compiler/register src/server.js
The same preload handles ESM imports, CommonJS require(), and Node's native TypeScript formats. It
also chains with TypeScript runners:
This is runtime JIT instrumentation, not AOT source rewriting: the hook generates validators
in-process on first use. Use a build plugin or the CLI when validator code must exist before Node
starts, or when new Function is unavailable.
Optional settings come from zod-compiler.json in the working directory:
output: "compact" keeps the Zod schema and the compiled fast path, delegating cold error production
to Zod. Full "schema" output stays the default. "bag" is unavailable here: a load hook cannot safely
replace already-linked ESM export bindings.
import { defineConfig } from "@rsbuild/core";import zodCompiler from "zod-compiler/rsbuild";export default defineConfig({ plugins: [zodCompiler()],});
Note: Vitest is detected automatically (via the VITEST env var), so tests exercise the same
validators that ship to production, performance included. Pass apply: "build" to have tests use the
plain Zod fallback instead.
Bun
Applies wherever your code passes through a build step. Requires Bun ≥ 1.2.22.
Only expressions built from imported bindings and literals move; anything touching locals, this or
new Date() stays put. Combinator chains on imported schemas qualify via schemaNamePattern (default
/ZodSchema$/).
In auto mode hoisted schemas also compile, rescuing schemas that never leave a function (a slonik
query, a tRPC input) and are therefore invisible to export scanning: ~16,700 ns → ~14 ns per call.
Bundle Size & Cross-File Dedup
Validators share a runtime helper layer imported from one module, so each helper appears once per
bundle. Schemas in a file that share a structurally identical sub-shape emit its error walk once, worth
19-28% raw / 10-18% gzipped and scaling with how much the file repeats.
Build plugins serve that module from a resolve hook (virtual:zod-compiler/runtime, or
__zod-compiler-runtime__ on webpack and rspack). Turbopack has no such hook, so
it imports the real subpath zod-compiler/runtime instead, opt-in because it only pays off where the
host bundles that import.
Transpile-only esbuild builds (no --bundle) never fire the bundler's resolve hooks, so the
virtual: specifier would survive into dist/ and fail at runtime. Set codegenMode: "inline" to emit
helpers per file instead:
Automatic mode, unchanged sources, next dev and next build. Options go in the object form,
loaders: [{ loader: "zod-compiler/turbopack", options: { verbose: true } }], and must be plain JSON,
so hoist.schemaNamePattern takes a string, not a RegExp.
Three things worth knowing:
Keep the content pattern loose. Narrowing it to "zod" skips zod/v4, zod/mini and the
zod-compiler import behind schemas: "explicit", leaving those files quietly uncompiled.
codegenMode: "lean" is App-Router-only. It shares one copy of the helpers across the bundle,
but Pages Router server code externalizes node_modules imports unless
bundlePagesRouterDependencies
is on, so a devDependency install throws ERR_MODULE_NOT_FOUND in production.
A "use server" file can only export async functions, so keep schemas there inside a function.
Hoisting still compiles them. "use client" modules need nothing special.
Turbopack caches loader results itself, so cache .next/cache in CI rather than
node_modules/.cache/zod-compiler. next dev --webpack / next build --webpack still work, with
zod-compiler/webpack in a webpack() config as usual.
SWC
A programmatic @swc/core bridge wrapping transform(), not a .swcrc plugin. Install
@swc/core, then:
Defaults codegenMode to "inline" (SWC has no virtual-module hook); pass
zodCompiler: { codegenMode: "lean" } if a later bundler resolves the runtime specifier. Honours
include/exclude and keeps no disk cache.
React Native / Expo
There is no Metro plugin, since unplugin has no Metro adapter. Use the CLI; Metro
bundles what it emits as ordinary source:
The step pays for itself: Hermes ships no JIT and no new Function, so Zod's own object fast path
is unavailable on device and jit() cannot run there at all.
Keep schema modules free of react-native and expo-* imports, transitively. Discovery executes each
file and its import graph in Node, and one that throws falls back to runtime Zod silently.
Compact Output (output: "compact")
Compiles the fast path and delegates the cold error path to the retained Zod schema, dropping
~73% raw / ~71% gzipped across 50 distinct schemas. The hot path is unchanged and errors are Zod's
own; only reading .error invokes Zod. Mutually exclusive with output: "bag".
zodCompiler({ output: "compact" });
Workers and Serverless Startup
Workers construct every imported schema at module init, even when an isolate validates only a few, so
compiling all of them trades bundle size and startup work for validation speed. Compact output trims
the generated error path but does not make construction lazy.
Narrow include or use schemas: "explicit" to skip intermediate exports. Use output: "bag" where
consumers need no Zod APIs (.shape, .extend(), .meta(), z.toJSONSchema()); it drops the
retained schema entirely.
Measure startup separately from validation throughput, on the target deployment and bundle.
Auto Mode: Side Effects Warning
Auto mode executes files to inspect their exports, so a file with schema-shaped exports and side
effects runs them at build time. Limit the scan with include.
For the common env.ts that validates process.env and exits, zod-compiler sets
process.env.ZOD_COMPILER during discovery and intercepts process.exit, so the build never crashes.
Those files fall back to runtime Zod. To keep them compiled, guard on it:
if (!process.env.ZOD_COMPILER) { // ...validate and exit}
With @t3-oss/env-*, pass skipValidation: !!process.env.ZOD_COMPILER.
A schema whose SHAPE branches on an env var is baked at build time, and the cache key does not include
the environment. Give each environment its own cache directory if you share one across them.
Large projects and CI
Discovery executes each schema file inside the bundler's process, so the first cold run is the
expensive one. Later runs hit the persistent cache.
Scope discovery with include; set ZOD_COMPILER_TIMING=1 for a per-phase breakdown. Files that
never mention zod cost nothing.
Parallel Transforms
Discovery runs one file at a time on the bundler's thread so concurrent transforms cannot
double-execute a shared dependency. parallel moves whole transforms onto worker threads, each with
its own loader and module cache.
zodCompiler({ parallel: true }); // one worker per core, less one, capped at 4zodCompiler({ parallel: 2 }); // or pick the count yourself
Whether it pays depends on your import graph, not your core count. A module shared by many
schema files is executed once in-process and once per worker here. Files with independent graphs
win; files chained through each other can lose. Both rows below are 120 files of 8 schemas each on
12 performance cores, differing only in whether the files import one another:
Transform (120 files)
in-process
n=2
n=4
n=8
n=12
independent graphs
3,633 ms
2,263 ms
1,508 ms
1,786 ms
2,119 ms
120-deep import chain
945 ms
977 ms
1,045 ms
1,796 ms
3,332 ms
Measure before adopting it: ZOD_COMPILER_TIMING=1 prints the per-phase breakdown, and discover is
the line workers move. Throughput peaks around four workers and declines past it, as every extra
worker re-executes more graph and holds another copy in memory.
Emitted code, sourcemaps and cache entries are identical either way, and parallel is not part of the
cache key, so parallel and serial builds share one cache. A worker that cannot start or dies mid-build
has its file retried in-process.
A warm cache still beats parallelism and costs no memory. Reach for parallel on cold runs.
Framework Examples
Nothing framework-specific is needed. Exported schemas are compiled in place, so anything accepting a
Zod schema picks up the compiled version:
The same applies to any Standard Schema consumer: ~standard.validate
routes through the compiled validator.
Compiled methods live on the schema object, so Zod's functional API (z.safeParse(Schema, x)) and a
compiled schema composed into an uncompiled parent stay on plain Zod.
Schema Diagnostics
Check coverage and Fast Path eligibility before compiling:
npx zod-compiler check src/schemas.ts
Output:
src/schemas.ts CreateUserSchema — 100% compiled (4/4 nodes) | Fast Path: eligible └─ ✓ object ├─ ✓ string .name ├─ ✓ string .email ├─ ✓ number .age └─ ✓ enum .role OrderSchema — 67% compiled (2/3 nodes) | Fast Path: ineligible (fallback (transform)) └─ ✓ object ├─ ✓ string .id └─ ✓ object .metadata ├─ ✓ string .metadata.region └─ ✗ fallback .metadata.audit (transform) hint: Extract transform into a separate post-processing step Fallbacks: ✗ .metadata.audit — transform Extract transform into a separate post-processing step
CI Integration
# JSON outputnpx zod-compiler check src/schemas.ts --json# Fail if any schema below 80% coveragenpx zod-compiler check src/schemas.ts --json --fail-under 80
Flag
Description
--json
Structured JSON output
--fail-under <pct>
Exit code 1 if coverage below threshold
--no-color
Disable colored output
What Gets Compiled
Fully Compiled (up to 43x faster)
Every Zod type except the fallbacks below: all primitives, object / strictObject / looseObject,
array, tuple, record, set, map, union, discriminatedUnion, intersection, pipe,
the optional / nullable / readonly / default / catch / coerce wrappers, templateLiteral,
recursive lazy (self, mutual and nested), custom / instanceof, and
transform / refine / superRefine.
All standard checks are supported: min, max, length, email, uuid, regex, int, positive,
multipleOf, includes, startsWith, and the rest.
Falls Back to Zod (Still Works, Not Faster)
A schema delegates to Zod when it reaches JavaScript the generated code cannot reproduce:
Construct
Why
.check(fn), superRefine + later checks
The callback holds Zod's payload unmediated, or fatal aborts Zod's chain
ctx-taking or async callbacks
Needs Zod's parse context / the async pipeline
z.jwt()
Algorithmic format (signature parsing)
Overlapping or policy-sensitive object intersections
Zod's independent parse-and-merge semantics cannot be safely collapsed
.readonly() over a pass-through container
Zod freezes the output it rebuilt; these are the caller's own input
Dynamic error maps, unresolvable z.lazy()
Not knowable at build time
Everything else compiles, including context-free preprocess callbacks and
transform/refine/superRefine whether or not the callback captures. A zero-capture one is inlined,
a capturing one called by reference. Delegation is per-sub-schema: one uncompilable field goes to Zod,
not the whole object. Run zod-compiler check to see what compiled.
Behavioral Differences from Zod
Compiled validators match Zod on verdicts, output data and error messages, including issue ordering.
Three things differ by design:
Behavior
Zod
zod-compiler
Record key iteration
Own enumerable keys, symbols included
Own enumerable string keys only
Container output identity
A fresh array / set / map / object
The input container, by reference (array holes and the input's key order survive); a rebuilt object is fresh and in zod's key order
Per-call parse params
safeParse(x, { error, reportInput }) honoured
Ignored; global z.config() maps still apply
Schema-level error and z.config() maps are unaffected; for a per-call map use
z.safeParse(Schema, x, params).
z.object() strips unknown keys exactly as Zod does, so its output is always a fresh object.
Benchmark
5-way comparison: Zod v3 vs Zod v4 vs zod-compiler vs Typia vs AJV
Scenario
Zod v3
Zod v4
zod-compiler
Typia
AJV
vs Zod v4
simple string
13.1M
15.9M
17.3M
18.0M
17.6M
1.1x
string (min/max)
12.3M
7.3M
17.3M
17.2M
15.6M
2.4x
number (int+positive)
12.4M
9.7M
17.5M
17.7M
17.0M
1.8x
enum
11.6M
15.5M
17.8M
18.1M
17.5M
1.1x
bigint (min/max)
11.9M
8.6M
17.3M
—
—
2.0x
tuple [string, int, bool]
5.5M
7.4M
16.7M
16.0M
15.8M
2.3x
record<string, number>
3.2M
2.5M
12.9M
12.0M
15.2M
5.1x
set<string> (5 items)
3.6M
2.3M
15.3M
—
—
6.8x
set<string> (20 items)
1.3M
679K
12.2M
—
—
18x
map<string, number> (5 entries)
2.0M
1.3M
13.5M
—
—
10x
map<string, number> (20 entries)
628K
346K
8.5M
—
—
25x
pipe (non-transform)
8.8M
4.7M
16.9M
—
—
3.6x
discriminatedUnion (3 variants)
3.4M
5.2M
17.1M
16.5M
7.9M
3.3x
discriminatedUnion (8 variants, rotating)
2.6M
4.6M
10.5M
—
—
2.3x
plain union of 8 tagged objects (auto-discrim.)
357K
1.3M
10.5M
—
—
7.9x
strict object (DB row)
1.8M
2.9M
11.4M
—
—
3.8x
medium object (valid)
1.9M
2.3M
9.8M
11.1M
7.6M
4.2x
medium object (extra keys stripped)
1.8M
2.1M
9.7M
—
—
4.6x
medium object (invalid)
517K
364K
15.9M
2.8M
7.5M
44x
large object (10 items)
120K
175K
5.3M
6.0M
1.2M
30x
large object (100 items)
13K
18K
764K
1.3M
124K
43x
readonly field (wrapper compiles away)
3.1M
6.6M
17.8M
—
—
2.7x
readonly root object (rebuild + freeze)
2.9M
5.6M
13.5M
—
—
2.4x
readonly array (delegates to Zod)
4.0M
4.4M
4.4M
—
—
1.0x
recursive tree (7 nodes)
574K
997K
9.0M
11.9M
4.8M
9.0x
recursive tree (121 nodes)
32K
58K
986K
1.9M
375K
17x
nested recursion (7 nodes)
390K
696K
7.8M
10.5M
2.9M
11x
nested recursion (121 nodes)
24K
42K
816K
1.6M
205K
20x
deeply nested object (243 leaves)
11K
28K
845K
1.0M
125K
30x
event log (combined)
375K
808K
7.6M
—
—
9.4x
catalog product with image URLs (valid)
432K
467K
2.1M
—
—
4.6x
catalog product with image URLs (invalid)
114K
106K
14.8M
—
—
140x
catalog page (20 products)
21K
23K
122K
—
—
5.2x
object with transform (zero-capture)
1.1M
1.9M
7.6M
—
—
4.0x
array 10 × transform (zero-capture)
123K
209K
4.3M
—
—
21x
array 50 × transform (zero-capture)
26K
41K
1.0M
—
—
25x
object with captured transform
1.2M
8.3M
16.2M
—
—
2.0x
object with captured refine (cross-field)
1.5M
2.2M
11.7M
—
—
5.3x
object with superRefine (cross-field)
1.5M
2.2M
9.6M
—
—
4.3x
coerced query object (valid)
1.8M
3.0M
5.4M
—
—
1.8x
coerced query object (invalid)
1.0M
837K
10.6M
—
—
13x
preprocessed query object (valid)
432K
1.8M
5.4M
—
—
3.0x
preprocessed query object (invalid)
393K
796K
12.7M
—
—
16x
stringbool config object (valid)
—
2.8M
6.3M
—
—
2.2x
stringbool config object (invalid)
—
698K
13.5M
—
—
19x
custom/instanceof request (valid)
979K
3.2M
10.4M
—
—
3.3x
custom/instanceof request (invalid)
795K
955K
13.6M
—
—
14x
disjoint object intersection (valid)
1.4M
1.6M
9.7M
—
—
6.0x
disjoint object intersection (invalid)
494K
335K
15.7M
—
—
47x
ops/s, higher is better. vp test bench on an Apple M4 Max (zod 4.5.2, zod v3 3.23.8, typia 12, ajv 8),
best of three runs. The harness costs ~60 ns per iteration, so the fastest rows sit at that floor and gaps
between the AOT columns there are noise, not real.
Nested objects, arrays and recursive types gain the most. Rejection is fast because a failed
safeParse defers building the error until .error is read. Zod 4.5 stopped capturing a stack trace
there too, narrowing the gap on rejected input.
vp run benchmark # run locally
Performance Architecture
A schema compiles to a fast path — one zero-allocation && chain, shared by .is() and
parse() — plus a slow path that collects errors only on failure, deferred until .error is read.
Schemas that reshape their input (stripping objects, coercions, stringbool, z.url(), defaults,
transforms, context-free preprocessors, disjoint-key intersections) instead validate and rebuild in a
single pass that bails on the first failure.
Other optimizations:
Regexes pre-compiled, bounded repeats unrolled; z.email() is a linear scan, not a backtracking regex.
Checks run cheapest-first, regardless of declaration order.
Discriminated unions dispatch through a switch; plain tagged unions are auto-discriminated into one.
z.custom() / z.instanceof() compile to a direct predicate call.
Oversized check functions are split to stay within V8's optimizer budget.
Intersections and custom keep the original Zod schema to construct issues, so rejections match Zod
exactly without slowing the hot path.