Zod to TypeScript Type Generator

Common errors

• Error: Zod schema version mismatch. `zod-to-ts` v2.x requires Zod v4.x.

  cause Attempting to use `zod-to-ts` v2 with an incompatible Zod v3.x installation.
  fix Upgrade your `zod` package to version 4 or higher: `npm install zod@^4`.

• Error: Cannot represent a Zod schema of type 'ZodTransformer' as a TypeScript type.

  cause A `z.transform()` or `z.custom()` Zod schema was encountered without configuring the `unrepresentable` option.
  fix Pass `{ unrepresentable: 'any' }` in the options object to `zodToTs` to allow `any` to be generated for unrepresentable types, or modify your Zod schema to avoid these constructs.

• TypeError: (intermediate value).toArray is not a function

  cause Trying to iterate over the `Map.prototype.values()` iterator returned by `auxiliaryTypeStore.definitions.values()` by calling a non-existent `toArray()` method directly.
  fix Use `Array.from(auxiliaryTypeStore.definitions.values())` to correctly convert the iterator into an array before further processing like `map()`.

Warnings

• breaking Version 2.0.0 of `zod-to-ts` dropped support for Zod v3. Only Zod v4 and newer versions are supported for runtime schema processing.
  Fix: Ensure your project uses `zod@^4.0.0` or higher. Upgrade Zod if necessary using `npm install zod@^4`.
• breaking The API for overriding types changed in v2.0.0. The `overrides` option is now expected to be a `Map` of Zod types to custom TypeScript nodes, replacing previous object-based configurations.
  Fix: Update your type override configuration to use the new `Map`-based API as described in the documentation.
• gotcha Zod APIs like `z.transform()` and `z.custom()` cannot be accurately represented as static TypeScript types. By default, `zod-to-ts` will throw an error if these are encountered.
  Fix: To bypass the error and generate `any` for unrepresentable types, pass `{ unrepresentable: 'any' }` in the options object to `zodToTs`. Alternatively, refactor your schema to avoid these constructs if strict type generation is required.
• gotcha Recursive Zod schemas (e.g., an object referencing itself) require the `createAuxiliaryTypeStore` and passing an `auxiliaryTypeStore` instance to `zodToTs` to generate correct helper types. Without it, the generated type node might be incomplete or incorrect.
  Fix: Before calling `zodToTs` with a recursive schema, initialize `const auxiliaryTypeStore = createAuxiliaryTypeStore()` and pass it in the options: `{ auxiliaryTypeStore }`. Remember to process the `auxiliaryTypeStore.definitions` for all generated helper types.

Install

• npm install zod-to-ts npm
• yarn add zod-to-ts yarn
• pnpm add zod-to-ts pnpm

Imports

• zodToTs
  wrong:

  const { zodToTs } = require('zod-to-ts')

  correct:

  import { zodToTs } from 'zod-to-ts'

  This package is primarily designed for ESM usage. While CommonJS `require` might work with some bundler configurations, ESM `import` is the recommended and best-supported approach.
• createAuxiliaryTypeStore
  wrong:

  const { createAuxiliaryTypeStore } = require('zod-to-ts')

  correct:

  import { createAuxiliaryTypeStore } from 'zod-to-ts'

  Essential for correctly generating types for recursive Zod schemas, which often require helper types.
• createTypeAlias
  wrong:

  const { createTypeAlias } = require('zod-to-ts')

  correct:

  import { createTypeAlias } from 'zod-to-ts'

  Utility to wrap a raw TypeScript AST node into a full `type` alias declaration, making it easier to print.
• printNode
  wrong:

  const { printNode } = require('zod-to-ts')

  correct:

  import { printNode } from 'zod-to-ts'

  Used to convert any TypeScript AST node (including those returned by `zodToTs` or `createTypeAlias`) into its string representation.

Quickstart

Demonstrates converting complex Zod object schemas, including nested objects, arrays, and recursive structures, into TypeScript type aliases and printing them, showing how auxiliary types are generated for recursion.

import { z } from 'zod';
import { zodToTs, createAuxiliaryTypeStore, createTypeAlias, printNode } from 'zod-to-ts';

const CategorySchema = z.object({
  name: z.string(),
  subcategories: z.lazy(() => z.array(CategorySchema)),
});

const UserSchema = z.object({
  username: z.string().describe('User\'s unique identifier'),
  age: z.number().int().positive(),
  roles: z.array(z.literal('admin').or(z.literal('editor')).or(z.literal('viewer'))),
  inventory: z.object({
    name: z.string().min(1),
    itemId: z.number().int().positive(),
    quantity: z.number().int().min(0).optional(),
  }).array().describe('List of user\'s owned items'),
  favoriteCategory: CategorySchema,
});

const auxiliaryTypeStore = createAuxiliaryTypeStore();
const { node: userNode } = zodToTs(UserSchema, { auxiliaryTypeStore });

const userTypeAlias = createTypeAlias(userNode, 'User');
const userTypeString = printNode(userTypeAlias);
console.log('--- User Type ---');
console.log(userTypeString);

console.log('\n--- Auxiliary Types (for recursion) ---');
// Extract and print auxiliary types if any (e.g., for CategorySchema recursion)
const auxiliaryTypePreamble = Array.from(auxiliaryTypeStore.definitions.values())
  .map((definition) => printNode(definition.node))
  .join('\n');
console.log(auxiliaryTypePreamble);