bjornmelin/zod-v4

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

| Task | Start Here | | --- | --- | | v3 migration or deprecated API cleanup | rules/_index.md, then references/migration-v3-to-v4.md | | User input, env, HTTP, DB, queue, or JSON boundaries | parse-*, schema-*, and references/codecs-v4.md | | Current schema APIs, string formats, records, template literals, XOR, defaults | references/schema-surface-v4.md | | UI/API/CLI error messages | error-*, migrate-error-*, and references/errors-v4.md | | Object composition, strictness, or refined schemas | object-* rules | | JSON Schema/OpenAPI export | jsonschema-*, meta-*, and references/json-schema-v4.md | | Bidirectional wire/internal transforms | codec-* and references/codecs-v4.md | | React Hook Form, tRPC, Hono, or Next.js actions | references/ecosystem-*.md | | Zod Mini, package exports, or library-author work | references/package-surfaces-v4.md | | Repo audit before a migration | references/audit.md and scripts/zod-audit.ts |

Priority Rules

1. Validate at boundaries: use safeParse for untrusted input, parseAsync for async refinements/transforms, and never trust JSON.parse output.
2. 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.
3. 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.
4. Use codecs when direction matters: prefer z.codec, z.decode, z.encode, and z.invertCodec for reversible wire/internal mappings.
5. 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

| Priority | Category | Prefix | | --- | --- | --- | | 1 | Migration + deprecations | migrate- | | 2 | Parsing + boundaries | parse- | | 3 | Error handling | error- | | 4 | Objects + composition | object- | | 5 | Schema definitions | schema- | | 6 | Metadata + registries | meta- | | 7 | JSON Schema/OpenAPI | jsonschema- | | 8 | Codecs | codec- | | 9 | Package surfaces | package- |

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