Zod Global Configuration#

z.config() is the public API for reading and mutating Zod's global settings at runtime. Internally it operates on a single object stored at globalThis.__zod_globalConfig — the single source of truth regardless of how many copies of Zod are loaded in the same JavaScript realm (CJS, ESM, multiple bundles in a monorepo). 1

The $ZodConfig Shape#

The config object is typed as $ZodConfig and has five fields:

How It Works#

At module load time, Zod initialises the shared object with a single ??= assignment 2:

(globalThis as GlobalThisWithConfig).__zod_globalConfig ??= {};
export const globalConfig = (globalThis as GlobalThisWithConfig).__zod_globalConfig!;

z.config(newConfig?) merges newConfig into that object via Object.assign and returns it 3. Because every loaded Zod copy points at the same globalThis property, one call updates all of them.

Pre-import bootstrap — because of the ??= guard, you can pre-populate the config before Zod even loads:

<script>globalThis.__zod_globalConfig = { jitless: true };</script>
<script type="module" src="app.js"></script>

Zod preserves that exact object identity on import. 4 5

Error Map Precedence#

customError and localeError slot into the global layers of Zod's error-resolution chain. From highest to lowest priority 6:

1. Check-level error (z.string().min(5, "Too short!"))
2. Schema-level error (z.string("Invalid name"))
3. Per-parse error (.parse(data, { error: … }))
4. customError (set via z.config({ customError: … }))
5. localeError (set via z.config(z.locales.en()))

Any error map may return undefined to defer to the next level in the chain.

Cross-Bundle Collision Risk#

Because globalThis.__zod_globalConfig is unversioned and shared, a third-party SDK that bundles its own copy of Zod and calls z.config({ customError: … }) will silently overwrite the application's global error map — and vice versa. 5

This is the same trade-off already accepted for globalThis.__zod_globalRegistry. Mitigations:

• Prefer schema-level or per-parse error maps in library code; they have higher precedence and do not touch global state.
• If you must set customError from a library, guard it to avoid clobbering an existing value: check z.config().customError before assigning.
• For jitless, the flag is boolean and idempotent, so multiple writers are safe as long as they all agree on the value.

Key Source Files#