gajus/babel-plugin-zod-hoist

README

Babel Plugin to Hoist Zod Schemas

Hoists Zod schema definitions to the top of the file.

Note

Deprecated in favor of https://github.com/gajus/zod-compiler

This:

function getSchema() {
  return z.object({ name: z.string() });
}

Becomes this:

const _schema_94b7f = z.object({
  name: z.string(),
});
function getSchema() {
  return _schema_94b7f;
}

Motivation

Initializing Zod schemas is expensive.

By hoisting the schema to the top of the file, we can avoid re-initializing the schema every time we use it.

Results (Zod 4.3.5, Node 22):

┌────────────────────────────────────────┬──────────────┬───────────────┬─────────┐
│                Scenario                │ Inline ops/s │ Hoisted ops/s │ Speedup │
├────────────────────────────────────────┼──────────────┼───────────────┼─────────┤
│ Simple object z.object({ name })       │          78K │         31.5M │    402x │
├────────────────────────────────────────┼──────────────┼───────────────┼─────────┤
│ Chained string .min().max().optional() │          37K │         15.3M │    414x │
├────────────────────────────────────────┼──────────────┼───────────────┼─────────┤
│ API payload (email, uuid, enum, array) │          19K │          3.0M │    157x │
├────────────────────────────────────────┼──────────────┼───────────────┼─────────┤
│ Nested object w/ array of objects      │          14K │          3.1M │    218x │
├────────────────────────────────────────┼──────────────┼───────────────┼─────────┤
│ Discriminated union                    │          24K │         15.1M │    627x │
├────────────────────────────────────────┼──────────────┼───────────────┼─────────┤
│ Derived .extend() on imported base     │          58K │          6.6M │    113x │
└────────────────────────────────────────┴──────────────┴───────────────┴─────────┘

Hoisting is 113–627x faster depending on the schema shape.

Why Use This?

Performance Boost: Prevents unnecessary re-initialization.
Zero Mental Overhead: Write normal Zod code - the hoisting happens automatically.
No Code Changes Required: Works with your existing codebase without modifications.

Installation

npm install --save-dev babel-plugin-zod-hoist

Usage

Add the plugin to your Babel configuration:

{
  "plugins": ["babel-plugin-zod-hoist"]
}

Hoisting derived schemas

The plugin also hoists schemas derived from an imported base schema via Zod combinators (.extend(), .pick(), .omit(), .merge(), .partial(), and so on).

This:

import { UserShape } from './shapes';

function getRowSchema() {
  return UserShape.extend({ rowId: z.number() });
}

Becomes this:

const _schema_d117fccf = UserShape.extend({
  rowId: z.number(),
});
import { UserShape } from './shapes';
function getRowSchema() {
  return _schema_d117fccf;
}

Hoisted declarations are placed above the import statements. This is safe because ES module imports are initialized before any other module code runs.

Because Babel has no type information, the plugin needs a signal that the base is actually a Zod schema before hoisting a chain like Base.extend(...) — otherwise it might rewrite unrelated APIs such as dayjs.extend(plugin). A combinator chain on a non-z base is hoisted when either:

the chain contains a z.* call somewhere (e.g. UserShape.extend({ rowId: z.number() })), or
the base identifier's name matches schemaNamePattern (default /ZodSchema$/).

Schemas that reference local variables, this, or top-level const/let/var bindings are never hoisted, since that could change behavior or cause temporal dead zone errors. Only schemas built solely from imports and literals are hoisted.

Options

Pass options using the array form in your Babel configuration:

// babel.config.js
export default {
  plugins: [['babel-plugin-zod-hoist', { schemaNamePattern: /Shape$/ }]],
};

`schemaNamePattern`

Type: RegExp | string | null — Default: /ZodSchema$/

A combinator chain whose base (root) identifier name matches this pattern is treated as a Zod schema and hoisted even when the chain contains no inline z.* call. This lets schemas built purely from other schemas hoist:

import { UserZodSchema } from './schemas';

function getPublicSchema() {
  return UserZodSchema.pick({ name: true, email: true });
}

Becomes this:

const _schema_1865b49b = UserZodSchema.pick({
  name: true,
  email: true,
});
import { UserZodSchema } from './schemas';
function getPublicSchema() {
  return _schema_1865b49b;
}

The option accepts:

a RegExp — { schemaNamePattern: /Shape$/ };
a string, compiled as a RegExp source (anchor with $ for a suffix) — useful for JSON configs that cannot hold a RegExp literal:
```
{
  "plugins": [["babel-plugin-zod-hoist", { "schemaNamePattern": "Shape$" }]]
}
```
null — disables name-based matching, requiring an inline z.* call for every derived chain.

README

Babel Plugin to Hoist Zod Schemas

Hoists Zod schema definitions to the top of the file.

Note

Deprecated in favor of https://github.com/gajus/zod-compiler

This:

function getSchema() {
  return z.object({ name: z.string() });
}

Becomes this:

const _schema_94b7f = z.object({
  name: z.string(),
});
function getSchema() {
  return _schema_94b7f;
}

Motivation

Initializing Zod schemas is expensive.

By hoisting the schema to the top of the file, we can avoid re-initializing the schema every time we use it.

Results (Zod 4.3.5, Node 22):

┌────────────────────────────────────────┬──────────────┬───────────────┬─────────┐
│                Scenario                │ Inline ops/s │ Hoisted ops/s │ Speedup │
├────────────────────────────────────────┼──────────────┼───────────────┼─────────┤
│ Simple object z.object({ name })       │          78K │         31.5M │    402x │
├────────────────────────────────────────┼──────────────┼───────────────┼─────────┤
│ Chained string .min().max().optional() │          37K │         15.3M │    414x │
├────────────────────────────────────────┼──────────────┼───────────────┼─────────┤
│ API payload (email, uuid, enum, array) │          19K │          3.0M │    157x │
├────────────────────────────────────────┼──────────────┼───────────────┼─────────┤
│ Nested object w/ array of objects      │          14K │          3.1M │    218x │
├────────────────────────────────────────┼──────────────┼───────────────┼─────────┤
│ Discriminated union                    │          24K │         15.1M │    627x │
├────────────────────────────────────────┼──────────────┼───────────────┼─────────┤
│ Derived .extend() on imported base     │          58K │          6.6M │    113x │
└────────────────────────────────────────┴──────────────┴───────────────┴─────────┘

Hoisting is 113–627x faster depending on the schema shape.

Why Use This?

Performance Boost: Prevents unnecessary re-initialization.
Zero Mental Overhead: Write normal Zod code - the hoisting happens automatically.
No Code Changes Required: Works with your existing codebase without modifications.

Installation

npm install --save-dev babel-plugin-zod-hoist

Usage

Add the plugin to your Babel configuration:

{
  "plugins": ["babel-plugin-zod-hoist"]
}

Hoisting derived schemas

The plugin also hoists schemas derived from an imported base schema via Zod combinators (.extend(), .pick(), .omit(), .merge(), .partial(), and so on).

This:

import { UserShape } from './shapes';

function getRowSchema() {
  return UserShape.extend({ rowId: z.number() });
}

Becomes this:

const _schema_d117fccf = UserShape.extend({
  rowId: z.number(),
});
import { UserShape } from './shapes';
function getRowSchema() {
  return _schema_d117fccf;
}

Hoisted declarations are placed above the import statements. This is safe because ES module imports are initialized before any other module code runs.

the chain contains a z.* call somewhere (e.g. UserShape.extend({ rowId: z.number() })), or
the base identifier's name matches schemaNamePattern (default /ZodSchema$/).

Options

Pass options using the array form in your Babel configuration:

// babel.config.js
export default {
  plugins: [['babel-plugin-zod-hoist', { schemaNamePattern: /Shape$/ }]],
};

`schemaNamePattern`

Type: RegExp | string | null — Default: /ZodSchema$/

import { UserZodSchema } from './schemas';

function getPublicSchema() {
  return UserZodSchema.pick({ name: true, email: true });
}

Becomes this:

const _schema_1865b49b = UserZodSchema.pick({
  name: true,
  email: true,
});
import { UserZodSchema } from './schemas';
function getPublicSchema() {
  return _schema_1865b49b;
}

The option accepts:

a RegExp — { schemaNamePattern: /Shape$/ };
a string, compiled as a RegExp source (anchor with $ for a suffix) — useful for JSON configs that cannot hold a RegExp literal:
```
{
  "plugins": [["babel-plugin-zod-hoist", { "schemaNamePattern": "Shape$" }]]
}
```
null — disables name-based matching, requiring an inline z.* call for every derived chain.

gem-hunter