zod-to-ts

library2.0.0jsnpmunverified

zod-to-ts generates TypeScript type definitions directly from Zod schemas, converting Zod's runtime validation objects into static TypeScript types. The current stable version is `2.0.0`, with recent releases focusing on supporting Zod v4 and improving the handling of complex type structures, especially recursion. Releases appear to be feature-driven, with new minor versions adding capabilities and major versions introducing breaking changes, particularly around Zod compatibility and internal API improvements. Key differentiators include its ability to generate TypeScript AST nodes directly for programmatic manipulation, robust support for recursive types through an auxiliary type system, and configurable output (e.g., 'input' vs. 'output' types for schemas using transformations or pipes). It also supports JSDoc comments from Zod's `.describe()` method, making generated types more descriptive. This library is crucial for projects aiming to maintain type safety and reduce boilerplate by deriving types directly from Zod validation logic.

serialization type-stubs

npm install zod-to-ts

github ↗package ↗

INSTALL

IMPORT

SIG · ZOD-TO-TS

zod-to-ts

serializationjavascriptv2.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

zodToTs

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

✗ const { zodToTs } = require('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

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

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

Essential for correctly generating types for recursive Zod schemas, which often require helper types.

createTypeAlias

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

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

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

printNode

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

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

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

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);

Debug

Known issues

breakingVersion 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`.

affects: >=2.0.0

breakingThe 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.

affects: >=2.0.0

gotchaZod 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.

affects: >=1.0.0

gotchaRecursive 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.

affects: >=2.0.0

Errors

Common errors & fixes

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

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.

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

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()`.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

typescriptrequiredRequired for TypeScript AST manipulation and type generation. It is a peer dependency.

zodrequiredCore dependency for defining schemas. It is a peer dependency, but v2.x of `zod-to-ts` strictly requires Zod v4+ at runtime.

Agent activity

44 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/sachinraja/zod-to-ts ↗

packagehttps://www.npmjs.com/package/zod-to-ts ↗