Skip to main content

cli/src

@zod-to-form/cli — Build-time CLI for generating React form components from Zod v4 schemas.

Drives the full code generation pipeline: loads a schema file, walks the Zod internal type tree via @zod-to-form/core, applies per-field overrides from z2f.config.ts, and emits static .tsx form components — optionally alongside a Next.js server action and a schema-lite file for optimized client-side validation.

Remarks​

Before using the CLI, decide: are you scripting (use runGenerate) or interacting (use npx zod-to-form)? For config authoring, always use defineConfig for type inference.

Use When​

  • You want a one-shot CLI command to generate a typed React form from a Zod schema — no runtime overhead, static output
  • You need watch-mode codegen that regenerates on schema file changes — --watch keeps the output in sync automatically
  • You want programmatic codegen from a Node.js script without spawning a child process — import runGenerate directly instead of using the CLI binary

Avoid When​

  • Runtime form rendering — use @zod-to-form/react for that; the CLI only emits static .tsx files
  • Browser environments — this package uses Node.js fs and path APIs not available in browsers
  • Projects that do not use Vite — the @zod-to-form/vite plugin covers that use case better with HMR integration

Pitfalls​

  • NEVER omit --config when calling the CLI — there is no fallback auto-discovery when --export is provided without a config; the command will error
  • NEVER rely on generated file content without checking wroteFile — when overwrite is false and the output file already exists, runGenerate returns wroteFile: false and leaves the existing file unchanged without throwing
  • NEVER mix CLI-generated components with components managed by the Vite plugin in the same module — the import paths and registry expectations differ

CLI​

Configuration​

Other​

FieldConfig​

Re-exports FieldConfig