Zod v4

🚀 Performance Improvements

Zod v4 delivers significant performance gains:

• String parsing is up to 2.6 times faster.

• Array parsing sees a 3x speed increase.

• Object parsing is up to 7x faster.

• TypeScript compilation performance has improved, with some operations reducing from 25,000 to 1,100 instantiations.

• The core bundle size has been reduced by 2x, and the new @zod/mini package offers a 6.6x smaller footprint with functional tree-shaking. Zod+7Medium+7Basic Utils+7

🧩 New Features

1. z.interface() for Recursive Types

Defining recursive schemas is now more straightforward with z.interface(), eliminating the need for z.lazy():GitHub+5Basic Utils+5Medium+5

typescript
CopyEditconst Category = z.interface({
  name: z.string(),
  get subcategories() {
    return z.array(Category);
  }
});

This approach simplifies the creation of recursive structures. Basic Utils

2. File Schema Validation

Zod v4 introduces z.file() for validating File instances, allowing constraints on size and MIME type:Zod+3Basic Utils+3Zod+3

typescript
CopyEditconst fileSchema = z.file()
  .min(10_000) // Minimum size in bytes
  .max(1_000_000) // Maximum size in bytes
  .type("image/png"); // MIME type

This feature is particularly useful for handling file uploads. Zod+3Zod+3Basic Utils+3

3. Metadata Registry

A new metadata system allows attaching strongly-typed metadata to schemas without polluting the schema definition itself. Metadata is stored in a separate registry:Zod

typescript
CopyEditimport { z } from "zod/v4";

const myRegistry = z.registry<{ title: string; description: string }>();
const emailSchema = z.string().email();
myRegistry.set(emailSchema, {
  title: "Email Address",
  description: "A valid email address."
});

This separation enhances modularity and clarity in schema definitions.

4. Internationalization (i18n)

Zod v4 supports locale-based error messages through z.config(), facilitating internationalization:Medium+4Basic Utils+4Zod+4

typescript
CopyEditz.config(z.locales.en()); // Set to English locale

This feature allows developers to provide validation messages in multiple languages. Basic Utils

5. Enhanced Error Handling

The new z.prettifyError() function converts ZodError instances into human-readable strings, improving debugging and user feedback:Basic Utils

typescript
CopyEditconst result = schema.safeParse(data);
if (!result.success) {
  console.log(z.prettifyError(result.error));
}

This enhancement streamlines error reporting. Best of JS+11Reddit+11Medium+11

🔁 Migration and Compatibility

To adopt Zod v4, ensure your project is using zod@^3.25.0 or later. Zod v4 is accessible via the /v4 subpath:Hacker News+3Zod+3Zod+3

typescript
CopyEditimport { z } from "zod/v4";

This approach allows for a gradual migration, as Zod v3 and v4 can coexist.

📦 Additional Enhancements

• z.stringbool(): Converts common truthy and falsy strings into boolean values, simplifying boolean parsing from user input.

• Improved JSON Schema Conversion: Enhanced compatibility with validation tools and support for frontend-backend schema sharing.

• Automatic Discriminator Detection: z.discriminatedUnion() now automatically detects the discriminator key, reducing boilerplate. Medium+4Basic Utils+4Zod+4

🎯 Conclusion

Zod v4 represents a significant advancement in schema validation for TypeScript, offering improved performance, enhanced features, and greater flexibility. Whether you're building APIs, forms, or complex data structures, Zod v4 provides the tools to write safer and more maintainable code.Basic Utils

For more information and detailed documentation, visit the official Zod v4 documentation.