TypeScript to Zod Schema Generator

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ...ts-to-zod/lib/index.mjs not supported.

  cause Attempting to import ts-to-zod in a CommonJS context without proper configuration, especially in Node.js environments that strictly enforce ESM module resolution for packages declaring 'type: module' or specific 'exports'.
  fix For Node.js projects, ensure your importing file is an ES Module (e.g., .mjs extension or 'type: module' in package.json) or adjust your build system to handle ESM. Alternatively, if your project needs to remain CommonJS, verify your Node.js version and module resolution settings are compatible with ts-to-zod's dual CJS/ESM exports.

• ZodError: Expected string, received number

  cause The generated Zod schema is not accurately reflecting the TypeScript type, or the data being validated does not conform to the expected type. This could be due to an issue with ts-to-zod's generation logic or an incorrect Zod version dependency.
  fix First, ensure you are using ts-to-zod v4+ with Zod v4+. If the issue persists, check your original TypeScript type definition for correctness and verify if any JSDoc tags are causing unexpected schema generation. If possible, remove `--skipValidation` to let ts-to-zod's internal validation catch discrepancies during generation. If the problem seems to be a bug in ts-to-zod, report it on GitHub.

• Type 'ZodObject<...>' is not assignable to type 'ZodType<...>' from 'zod' version 3 when ts-to-zod generates schemas for Zod v4.

  cause Mismatch between the Zod version ts-to-zod was configured for (v4+) and the Zod version installed in the consuming project (v3).
  fix Update your project's Zod dependency to version 4 or higher (e.g., `npm install zod@^4`). If you must use Zod v3, use ts-to-zod v3.x series.

Warnings

• breaking Major version 5 introduced breaking changes by refreshing dependencies and explicitly supporting ESM. While the package maintains CJS exports, users in mixed environments or those with older Node.js setups might encounter module resolution issues, primarily related to the internal restructuring for ESM support.
  Fix: Ensure your project is configured for ESM where ts-to-zod is imported, or verify your CJS setup correctly resolves module exports. Update Node.js to a supported version for optimal compatibility.
• breaking Version 4 introduced support for Zod v4. Projects using ts-to-zod v4+ must upgrade their Zod dependency to v4 or higher. Generated schemas will be incompatible with Zod v3.
  Fix: Update your project's Zod dependency to '^4' (e.g., `npm install zod@^4`) and regenerate all schemas. For Zod v3 support, use ts-to-zod v3.x series.
• gotcha As of version 5, ts-to-zod no longer embeds Prettier (or any other formatter) in its generation process. Generated schema files will not be automatically formatted.
  Fix: Integrate a code formatter like Prettier or BiomeJS into your build pipeline. The recommended approach is to use `pretty-quick` or a similar tool in your post-generation scripts.
• gotcha The internal validation mechanism, which compares generated Zod schemas against original TypeScript types, only applies to *exported* types and interfaces. Non-exported types will not be validated.
  Fix: Ensure all types you wish to be validated by ts-to-zod are exported in your TypeScript files. For private types, rely on your TypeScript compiler for type safety.
• gotcha Skipping internal schema validation using the `--skipValidation` flag is possible but strongly discouraged. This bypasses a crucial check that ensures compatibility between your TypeScript types and the generated Zod schemas, potentially leading to runtime validation errors.
  Fix: Avoid using `--skipValidation` unless absolutely necessary for debugging or specific edge cases. Address any validation errors reported by the tool to maintain schema integrity.

Install

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

Imports

• generateZodSchema
  wrong:

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

  correct:

  import { generateZodSchema } from 'ts-to-zod';

  The primary function for programmatically generating a single Zod schema string from a TypeScript type. Supports both ESM and CJS.
• generateZodSchemaFile
  wrong:

  import generateZodSchemaFile from 'ts-to-zod';

  correct:

  import { generateZodSchemaFile } from 'ts-to-zod';

  Used for programmatic generation of a Zod schema file. It's a named export, not a default export.
• run
  wrong:

  tsToZod.run(['src/input.ts', 'src/output.ts']);

  correct:

  import { run } from 'ts-to-zod';

  The programmatic entry point for invoking the ts-to-zod CLI from within a Node.js application. Accepts an array of arguments, similar to process.argv.

Quickstart

Demonstrates how to install ts-to-zod, generate Zod schemas from a TypeScript type definition file using the CLI, and then import and use the generated schemas for runtime validation.

// 1. Install ts-to-zod
// pnpm add --dev ts-to-zod
// or yarn add --dev ts-to-zod
// or npm install --save-dev ts-to-zod

// 2. Create a TypeScript type file (e.g., src/types.ts)
// export interface User {
//   id: string;
//   name: string;
//   email: string | null;
//   age?: number;
//   roles: 'admin' | 'editor' | 'viewer'[];
//   createdAt: Date;
// }

// 3. Generate Zod schemas using the CLI
// pnpm ts-to-zod src/types.ts src/schemas.ts

// 4. In another file (e.g., src/app.ts), import and use the generated schemas
import { UserSchema } from './schemas'; // Assuming User becomes UserSchema

// Example data conforming to the User type
const userData = {
  id: '123',
  name: 'John Doe',
  email: 'john@example.com',
  age: 30,
  roles: ['admin', 'viewer'],
  createdAt: new Date().toISOString(), // Zod's .datetime() expects ISO string by default
};

// Validate the data
try {
  const parsedUser = UserSchema.parse(userData);
  console.log('User data is valid:', parsedUser);
  // parsedUser now has the correct TypeScript type inferred from Zod: z.infer<typeof UserSchema>
} catch (error) {
  console.error('Validation error:', error);
}

// Example of invalid data
const invalidUserData = {
  id: 456, // Invalid type
  name: 'Jane Doe',
  email: null,
  roles: 'editor', // Invalid type, should be array
  createdAt: 'not-a-date', // Invalid date format
};

try {
  UserSchema.parse(invalidUserData);
} catch (error) {
  console.error('\nInvalid user data failed validation as expected:', error.errors);
}