Importing Zod full build versus mini build
The full Zod build is imported with 'import * as z from "zod"'. The mini build is imported with 'import * as z from "zod/mini"'. Both support the same basic API.
mini build
38 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Zod Mini codec methods
In Zod Mini, codec methods are called as z.parse(schema, value), z.decode(schema, value), z.encode(schema, value), z.decodeAsync(schema, value), z.safeDecode(schema, value), and z.safeDecodeAsync(schema, value) instead of as methods on the schema instance.
Zod Mini check method for constraints
In Zod Mini, constraints like minimum length are applied using the check method: z.string().check(z.minLength(5, 'Too short!')). In full Zod, the same constraint uses the min method: z.string().min(5, 'Too short!'). Custom errors can be passed to either as a string or object with error parameter.
Default error message differences between Zod and Zod Mini
When parsing fails with z.string().safeParse(12), the full Zod library produces the message 'Invalid input: expected string, received number', while Zod Mini produces just 'Invalid input'. The full library includes more detail about the expected type and received type.
Zod Core package purpose and scope
The zod/v4/core sub-package exports core classes and utilities for custom implementations. It is not intended for direct use but rather to be extended by other packages like Zod and Zod Mini. It implements base classes for schemas, checks, and errors.
Zod Core imports statement
Import Zod Core with: import * as z from "zod/v4/core";
Zod Core difference from zod package
The zod package implements a subclass of $ZodError called ZodError with additional convenience methods, while the zod/mini sub-package directly uses $ZodError without extending it.
zod/v4 is the flagship library
The zod/v4 package is the flagship library of the Zod ecosystem and strikes a balance between developer experience and bundle size that is ideal for the vast majority of applications. For applications with uncommonly strict constraints around bundle size, Zod Mini should be considered instead.
Zod Mini base class inheritance
All Zod Mini schemas extend the z.ZodMiniType base class, which in turn extends z.core.$ZodType from zod/v4/core. While this class implements far fewer methods than ZodType in zod, some particularly useful methods remain available.
Zod Mini parsing methods
Zod Mini schemas implement the same parsing methods as regular zod: .parse(), .parseAsync(), .safeParse(), and .safeParseAsync().
Zod Mini check functions available
Zod Mini provides the following check functions: z.lt(value), z.lte(value) with alias z.maximum(), z.gt(value), z.gte(value) with alias z.minimum(), z.positive(), z.negative(), z.nonpositive(), z.nonnegative(), z.multipleOf(value), z.maxSize(value), z.minSize(value), z.size(value), z.maxLength(value), z.minLength(value), z.length(value), z.regex(regex), z.lowercase(), z.uppercase(), z.includes(value), z.startsWith(value), z.endsWith(value), z.property(key, schema), and z.mime(value). Custom checks include z.refine() and z.check() which replaces .superRefine().
Zod Mini mutation and metadata functions
Zod Mini provides mutation functions that do not change inferred types: z.overwrite(value => newValue), z.normalize(), z.trim(), z.toLowerCase(), z.toUpperCase(). Metadata functions that register schemas in z.globalRegistry are: z.meta({ title: "...", description: "..." }) and z.describe("...").
Zod Mini register method
The .register() method registers a schema in a registry. Example: const myReg = z.registry<{title: string}>(); z.string().register(myReg, { title: "My cool string schema" });
Zod Mini brand method
The .brand() method brands a schema for type safety. Example: const USD = z.string().brand("USD");
Zod Mini clone method
The .clone(def) method returns an identical clone of the current schema using the provided definition. Example: const mySchema = z.string(); mySchema.clone(mySchema._zod.def);
Zod Mini no default locale
Zod Mini does not automatically load the English locale, unlike regular Zod. This reduces bundle size in scenarios where error messages are unnecessary, localized to a non-English language, or customized. By default, the message property of all issues will read "Invalid input". To load the English locale, use: import * as z from "zod/mini"; z.config(z.locales.en());
Zod Mini import and installation
Zod Mini is a tree-shakable variant of Zod. Install with npm install zod@^4.0.0 and import with import * as z from "zod/mini". It implements the exact same functionality as zod, but using a functional, tree-shakable API where you generally use functions in place of methods.
Zod Mini functional API versus method chaining
In regular Zod, schemas use method chaining like z.string().optional().nullable(). In Zod Mini, the same functionality uses nested functions like z.nullable(z.optional(z.string())). This functional approach enables better tree-shaking.
Zod Mini check method replaces individual methods
In regular Zod, you use chained methods like z.string().min(5).max(10).trim(). In Zod Mini, you pass checks into the .check() method: z.string().check(z.minLength(5), z.maxLength(10), z.trim()). This consolidation helps with tree-shaking.
Zod Mini bundle size reduction
For a simple boolean parse script, Zod Mini produces a 2.12kb gzipped bundle compared to 5.91kb for regular Zod, a 64% reduction. For a more complex schema with object types containing string, number, and boolean fields, Zod Mini produces 4.0kb compared to 13.1kb for regular Zod.
When to use Zod Mini
Use Zod Mini only if you have uncommonly strict constraints around bundle size. Bundle size on the scale of Zod (5-10kb typically) is only a meaningful concern when optimizing front-end bundles for users with slow mobile network connections in rural or developing areas. Backend development, AWS Lambda, and typical internet speeds do not justify the DX tradeoff.
Zod Mini DX drawbacks
The API of Zod Mini is more verbose and less discoverable than regular Zod. The methods in regular Zod's API are much easier to discover and autocomplete through Intellisense than the top-level functions in Zod Mini. It is not possible to quickly build a schema with chained APIs, making development experience less ergonomic.
Lambda cold start performance impact of bundle size
According to benchmark data, a 1kb bundle has a 171ms Lambda cold start time. Adding 128kb increases this to 176ms (5ms increase). Regular Zod is roughly 17kb when gzipped, corresponding to approximately 0.6ms increase in startup time. Bundle size at Zod's scale is not a meaningful concern for Lambda performance.
Zod Mini uses check() instead of refine()
Zod Mini uses .check() instead of .refine() for refinements. Example in Zod Mini: z.object({...}).check(z.refine((data) => data.password === data.confirm, {...})) vs standard Zod: z.object({...}).refine((data) => ...).
Zod Mini safeParse uses different function signature
In Zod Mini, safeParse is called differently: z.safeParse(schema, data) instead of schema.safeParse(data). Both return the same structure with .error.issues.
Zod Mini pipe syntax differs from standard Zod
Zod Mini pipes use z.pipe() function instead of .pipe() method. Example: z.pipe(z.string(), z.transform(val => val.length)) vs standard z.string().pipe(z.transform(val => val.length)).
Zod Mini uses _default() instead of default()
Zod Mini uses z._default(schema, value) instead of schema.default(value). Example: z._default(z.string(), "tuna") vs standard z.string().default("tuna").
Zod Mini catch() syntax
Zod Mini uses z.catch(schema, value) instead of schema.catch(value). Example: z.catch(z.number(), 42) vs standard z.number().catch(42).
Zod Mini readonly() syntax
Zod Mini uses z.readonly(schema) instead of schema.readonly(). Example: z.readonly(z.object({...})) vs standard z.object({...}).readonly().
Zod Mini parseAsync signature
Zod Mini uses z.parseAsync(schema, data) instead of schema.parseAsync(data).
Zod Mini parse signature
Zod Mini uses z.parse(schema, data) instead of schema.parse(data).
Zod Mini minLength and maximum utilities
Zod Mini uses z.minLength(8) and z.maximum(100) instead of .min().max() methods. Used with .check(): z.number().check(z.minimum(0), z.maximum(100)).
Zod Mini no .transform() method
Zod Mini does not have the .transform() convenience method. Must use z.pipe(schema, z.transform(...)) instead.
Zod Mini API uses functional tree-shakable functions instead of methods
Zod Mini replaces method-heavy APIs with functional equivalents. Instead of z.string().optional(), use z.optional(z.string()). Instead of z.string().or(z.number()), use z.union([z.string(), z.number()]). Instead of z.object({}).extend(), use z.extend(z.object({}), {}).
Zod Mini has identical parsing methods
Parsing methods in Zod Mini are identical to Zod: z.string().parse(), z.string().safeParse(), z.string().parseAsync(), and z.string().safeParseAsync() all work the same way.
Zod Mini .check() method for refinements
Zod Mini has a general-purpose .check() method used to add refinements to schemas, replacing the method-chaining approach in regular Zod.
Zod Mini available refinements and checks
Zod Mini exports the following top-level refinements: z.refine(), z.lt(), z.lte()/z.maximum(), z.gt(), z.gte()/z.minimum(), z.positive(), z.negative(), z.nonpositive(), z.nonnegative(), z.multipleOf(), z.maxSize(), z.minSize(), z.size(), z.maxLength(), z.minLength(), z.length(), z.regex(), z.lowercase(), z.uppercase(), z.includes(), z.startsWith(), z.endsWith(), z.property(), z.mime(). Overwrites include: z.overwrite(), z.normalize(), z.trim(), z.toLowerCase(), z.toUpperCase().
Zod Mini core bundle size 6.6x smaller than Zod 3
Zod Mini bundles to 1.88kb (gzip), which is an 85% reduction compared to Zod 3's 12.47kb. This is 6.6x smaller than Zod 3.