# release-zod-v4
Source: https://speakeasy.com/blog/release-zod-v4


import { Callout, Table } from "@/mdx/components";

<Callout title="Get Started" type="default">
  Zod v4 mini support is available now in all Speakeasy TypeScript SDKs. Enable
  it by modifying the `zodVersion: v4-mini` flag to your gen.yaml configuration.
</Callout>

Today we're releasing support for Zod v4 mini in all Speakeasy-generated TypeScript SDKs. This update brings bundle size reductions of ~10% while maintaining the runtime type safety that makes our SDKs reliable.

## Why Zod matters

When we [rebuilt our TypeScript generator](/post/how-we-built-universal-ts), Zod was a critical piece of the puzzle. It solved a fundamental problem: TypeScript has no runtime type safety. Types exist only at compile time, disappearing entirely when your code runs.

This creates real issues when working with APIs. Without runtime validation, there's no guarantee that:

- The data you send matches your API's requirements
- The responses you receive match your expectations
- Type mismatches get caught before they cause bugs

Zod gives us runtime type safety by validating API responses before your code uses them:

```typescript
import { SDK } from "@speakeasy/ecommerce-sdk";

async function run() {
  const sdk = new SDK();

  const products = await sdk.products.list();

  // Without Zod validation:
  // ❌ Runtime error: "Cannot read properties of undefined (reading 'amount')"
  console.log(product.price.amount);
}

// With Zod validation, fails fast with a clear error:
// ZodError: Required at path: ["product", "price"]
```

This catches API contract mismatches immediately with clear errors, rather than letting your code crash when it tries to access properties that don't exist.

## Every improvement counts

We're always asking ourselves: can we make our SDKs better? When Zod v4 was released, we saw an opportunity to improve bundle efficiency.

Zod v3 has served us well. In a typical SDK, it accounts for around 15% of the bundle size—about 20KB minified and gzipped. For many applications, this is a reasonable tradeoff for runtime type safety. But with Zod v4 mini offering better tree-shaking through its standalone function API, we could reduce that footprint even further without compromising on validation.

## Enter Zod v4 mini

Zod v4 introduced a new variant called "mini" that fundamentally changes how validation works. Instead of method chaining, it uses standalone functions:

```typescript
// Zod v3/v4 (method chaining)
const schema = z.string().optional().nullable();

// Zod v4 mini (standalone functions)
const schema = z.nullable(z.optional(z.string()));
```

This might look like a cosmetic change, but it enables better tree-shaking. Standalone functions are module-level exports that bundlers can analyze and eliminate when unused. A class-based API, by contrast, pulls in the entire class structure regardless of which methods you actually call.

Zod v4 mini clocks in at around 10KB minified and gzipped—about half the size of Zod v3's 20KB.

Beyond bundle size, Zod v4 delivers significant performance improvements:

- String parsing is 14.7x faster
- Array parsing is 7.4x faster
- Object parsing is 6.5x faster

## How this impacts Speakeasy SDKs

These library changes are entirely internal to our generated SDKs. Your SDK users don't need to change anything—they continue using the same class-based interface they're familiar with:

```typescript
import { Dub } from "dub";

const dub = new Dub({ token: process.env.DUB_API_KEY });

const result = await dub.links.create({
  url: "https://example.com",
  domain: "dub.sh",
});
```

Under the hood, we've migrated all validation logic to use Zod v4 mini's standalone functions. Here's what we're seeing in real-world SDKs:

<Table
  data={[
    {
      sdk: "Minimal with 1 method Zod v4-mini",
      bundled: "79.44 KB",
      bundledMinified: "31.26 KB",
      bundledMinifiedGzip: "9.95 KB",
    },
    {
      sdk: "Minimal with 1 method Zod v4",
      bundled: "156.90 KB",
      bundledMinified: "63.76 KB",
      bundledMinifiedGzip: "17.69 KB",
    },
    {
      sdk: "Minimal with 1 method Zod v3",
      bundled: "181.74 KB",
      bundledMinified: "72.01 KB",
      bundledMinifiedGzip: "18.17 KB",
    },
    {
      sdk: "@polar-sh/sdk Zod v4-mini",
      bundled: "1.25 MB",
      bundledMinified: "542.09 KB",
      bundledMinifiedGzip: "55.22 KB",
    },
    {
      sdk: "@polar-sh/sdk Zod v3",
      bundled: "1.37 MB",
      bundledMinified: "598.28 KB",
      bundledMinifiedGzip: "61.51 KB",
    },
    {
      sdk: "@mistralai/mistralai Zod v3",
      bundled: "582.72 KB",
      bundledMinified: "234.36 KB",
      bundledMinifiedGzip: "34.60 KB",
    },
    {
      sdk: "@mistralai/mistralai Zod v4-mini",
      bundled: "488.50 KB",
      bundledMinified: "191.61 KB",
      bundledMinifiedGzip: "28.66 KB",
    },
  ]}
  columns={[
    { key: "sdk", header: "SDK" },
    { key: "bundled", header: "Bundled" },
    { key: "bundledMinified", header: "Bundled & Minified" },
    { key: "bundledMinifiedGzip", header: "Bundled & Minified & GZIP" },
  ]}
/>

Your SDK users automatically benefit from:

- Smaller bundle sizes when building frontend applications (typically ~10% reduction)
- Better tree-shaking that only includes validation for the SDK methods they actually use
- Faster validation at runtime

We've also maintained backward compatibility. Thanks to [the forward thinking zod team](https://zod.dev/library-authors?id=how-to-support-zod-3-and-zod-4-simultaneously) our SDKs work regardless of whether v3 or v4 is installed in your project.

## Getting started

Zod v4 mini support is opt-in via your gen.yaml configuration file. Add the zodVersion flag to your TypeScript generation settings:

```yaml
typescript:
  version: 1.0.0
  zodVersion: v4-mini
```

Then regenerate your SDK:

```bash
speakeasy run
```

<Callout title="Note" type="info">
  Some edge cases may require sticking with Zod v3. For example, MCP servers
  currently have compatibility issues with Zod v4. We recommend testing the
  migration in a development environment before deploying to production.
</Callout>

## Looking forward

Zod v4 mini is part of our broader commitment to building TypeScript SDKs that work everywhere: from Node.js servers, to browser frontends to edge functions. Every improvement matters, especially in bundle-sensitive environments like edge functions and mobile applications.

If you're generating TypeScript SDKs with Speakeasy, we encourage you to try Zod v4 mini. The migration is straightforward, and you'll benefit from smaller bundles and faster validation.