Zod v4

Rule-first Zod v4.4.3 guidance for TypeScript. Start with the highest-risk matching rule, then load the linked reference only when deeper API detail is needed.

Quick Start

bun add zod@^4.4.3

import { z } from "zod";

const User = z.object({
  name: z.string().min(1, { error: "Required" }),
  email: z.email({ error: "Invalid email" }),
});

type User = z.infer<typeof User>;

Route By Task

Priority Rules

1. Validate at boundaries: use safeParse for untrusted input, parseAsync

for async refinements/transforms, and never trust JSON.parse output.

1. Prefer current v4 APIs: top-level string formats, z.enum, z.object

plus z.strictObject or z.looseObject, unified { error }, top-level error formatters, and z.toJSONSchema.

1. Avoid false enforcement: default imports, namespace root imports, and

one-arg z.record(valueSchema) are valid in Zod 4.4.3; treat them as local style or migration-advisory findings, not package-invalid code.

1. Use codecs when direction matters: prefer z.codec, z.decode,

z.encode, and z.invertCodec for reversible wire/internal mappings.

1. Use `zod/v4/core` only for library tooling: app code normally imports

from zod; bundle-sensitive app code can use zod/mini; schema tooling and library adapters should read references/package-surfaces-v4.md.

Rule Categories

Start with rules/_index.md. Each rule file has the failure mode, compact bad/good examples, and linked references when nuance matters.

Automation

Resolve skill_dir as the directory containing this skill before running bundled scripts.

Zod Audit

Run the Zod-specific report-only scanner:

bun "$skill_dir/scripts/zod-audit.ts" --root . --format text

Useful commands:

bun "$skill_dir/scripts/zod-audit.ts" --list-rules
bun "$skill_dir/scripts/zod-audit.ts" --list-checks
bun "$skill_dir/scripts/zod-audit.ts" --explain migrate-top-level-string-formats

Use --fail-on warn|error|info only after reviewing whether advisory rules are appropriate for the target repo.

AI Stack Scanner

Use the shared dependency-free scanner for broad AI-stack migration signals:

python3 "$skill_dir/scripts/ai_stack_scan.py" --root . --family zod-v4 --pretty

Treat scanner output as private local evidence. Verify each signal against the current code and Zod docs/source before editing.

Rule Maintenance

bun "$skill_dir/scripts/build-rules-index.ts"
bun "$skill_dir/scripts/check-skill-integrity.ts"

Schema Runner

Load a schema from a local module and exercise parse, decode/encode, or JSON Schema behavior:

bun "$skill_dir/scripts/zod-run.ts" --module src/schemas/user.ts --export User --mode safeParse --input '{"name":"A","email":"[email protected]"}'
bun "$skill_dir/scripts/zod-run.ts" --module src/schemas/date.ts --export IsoDate --mode encode --input '"2026-05-13T00:00:00.000Z"'
bun "$skill_dir/scripts/zod-run.ts" --module src/schemas/user.ts --export User --mode toJSONSchema --io input --target openapi-3.0

zod-run.ts imports the target module, so avoid modules with heavy side effects.

References

• Reference router: references/index.md
• Migration checklist: references/migration-v3-to-v4.md
• Schema surface highlights: references/schema-surface-v4.md
• Errors and formatting: references/errors-v4.md, references/error-formatting-v4.md
• Metadata and JSON Schema: references/metadata-registries-v4.md, references/json-schema-v4.md
• Codecs: references/codecs-v4.md
• Package surfaces, Mini, Core, and library authors: references/package-surfaces-v4.md
• Ecosystem: references/ecosystem-react-hook-form.md, references/ecosystem-trpc.md, references/ecosystem-hono.md, references/ecosystem-nextjs-server-actions.md
• Audit guide: references/audit.md
• Rule template: assets/templates/rule-template.md