Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.typesync.org/llms.txt

Use this file to discover all available pages before exploring further.

Generates Zod schemas for the specified Typesync schema and writes them to the specified file. The generated schemas mirror the same mapping rules used internally by typesync validate-data, so the structure and constraints stay in lockstep across runtime validation and code generation. Documentation captured in your schema definition is preserved in the output: model-level docs are emitted as JSDoc comments and as .describe(...) calls on the schema, and field-level docs are emitted as .describe(...) calls on the field’s value schema.

​
Usage

typesync generate-zod --definition <filePathOrPattern> --target <targetEnvironment> --outFile <filePath> --variant <v3|v4> --schemaNamePattern <schemaNamePattern> --emitInferredTypes --inferredTypeNamePattern <inferredTypeNamePattern> --indentation <indentation> --debug <debug>

​
Options

​
definition
string
required
The exact path or a Glob pattern to the definition file or files. Each definition file must be a YAML or JSON file containing model definitions.
  • Example single file path: definition/models.json
  • Example Glob pattern: 'definition/**/*.yml'
​
target
string
required
The target environment for which the types are generated. This option specifies the target SDK and version, ensuring that the output is compatible with the chosen environment. See the list of available targets here.
​
outFile
string
required
The path to the output file.
​
variant
"v3" | "v4"
default:"v4"
Which Zod major release the generated code should target. Pick the variant that matches the zod version installed in the consuming project. The two majors differ in a couple of API surface points (the z.record key argument and the strict / loose object factories) and the generator emits the right shape for each.
​
schemaNamePattern
string
default:"{modelName}Schema"
The pattern that controls how the generated Zod schema constants are named. The pattern must be a string that contains the "{modelName}" substring (this is a literal value).Example values:
  • "{modelName}Schema" → produces exports like UserSchema, PostSchema, AccountSchema etc.
  • "z{modelName}" → produces exports like zUser, zPost, zAccount etc.
​
emitInferredTypes
boolean
default:false
When enabled, the generator emits an inferred TypeScript type alongside each Zod schema. For a model named User with the default patterns, the output becomes:
export const UserSchema = z.strictObject({
  /* ... */
});
export type User = z.infer<typeof UserSchema>;
​
inferredTypeNamePattern
string
default:"{modelName}"
The pattern that controls how the inferred TypeScript types are named when --emitInferredTypes is set. The pattern must contain the literal substring "{modelName}". Ignored when --emitInferredTypes is not set.Example values:
  • "{modelName}" → produces types like User, Post, Account etc.
  • "{modelName}Type" → produces types like UserType, PostType, AccountType etc.
  • "I{modelName}" → produces types like IUser, IPost, IAccount etc.
​
indentation
int
default:2
Indentation or tab width for the generated code.
​
debug
boolean
default:false
Whether to enable debug logs.

​
Targets

generate-zod reuses the generate-ts target list. The --target option determines the runtime classes that the generated z.instanceof(...) checks resolve to — pick the target that matches the Firestore SDK you decode documents with.

​
Notes

  • References between models are emitted as z.lazy(() => OtherSchema). Using z.lazy defers identifier resolution until validation time, which keeps mutually recursive schemas working regardless of declaration order in the generated file.
  • Strict / loose objects map to z.strictObject / z.looseObject for v4 and to z.object(...).strict() / z.object(...).passthrough() for v3. Whether an object accepts additional fields is controlled by the additionalFields flag in the schema definition.
  • The Firestore SDK is only imported when at least one model uses timestamp or bytes. For the admin targets, bytes resolves to the Node global Buffer and does not trigger an SDK import on its own.