pedronauck/zod

Zod Best Practices

Comprehensive schema validation guide for Zod in TypeScript applications. Contains 43 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new Zod schemas
• Choosing between parse() and safeParse()
• Implementing type inference with z.infer
• Handling validation errors for user feedback
• Composing complex object schemas
• Using refinements and transforms
• Optimizing bundle size and validation performance
• Reviewing Zod code for best practices

Rule Categories by Priority

| Priority | Category | Impact | Prefix | | -------- | ------------------------ | ----------- | ---------- | | 1 | Schema Definition | CRITICAL | schema- | | 2 | Parsing & Validation | CRITICAL | parse- | | 3 | Type Inference | HIGH | type- | | 4 | Error Handling | HIGH | error- | | 5 | Object Schemas | MEDIUM-HIGH | object- | | 6 | Schema Composition | MEDIUM | compose- | | 7 | Refinements & Transforms | MEDIUM | refine- | | 8 | Performance & Bundle | LOW-MEDIUM | perf- |

Quick Reference

1. Schema Definition (CRITICAL)

• schema-use-primitives-correctly - Use correct primitive schemas for each type
• schema-use-unknown-not-any - Use z.unknown() instead of z.any() for type safety
• schema-avoid-optional-abuse - Avoid overusing optional fields
• schema-string-validations - Apply string validations at schema definition
• schema-use-enums - Use enums for fixed string values
• schema-coercion-for-form-data - Use coercion for form and query data

2. Parsing & Validation (CRITICAL)

• parse-use-safeparse - Use safeParse() for user input
• parse-async-for-async-refinements - Use parseAsync for async refinements
• parse-handle-all-issues - Handle all validation issues not just first
• parse-validate-early - Validate at system boundaries
• parse-avoid-double-validation - Avoid validating same data twice
• parse-never-trust-json - Never trust JSON.parse output

3. Type Inference (HIGH)

• type-use-z-infer - Use z.infer instead of manual types
• type-input-vs-output - Distinguish z.input from z.infer for transforms
• type-export-schemas-and-types - Export both schemas and inferred types
• type-branded-types - Use branded types for domain safety
• type-enable-strict-mode - Enable TypeScript strict mode

4. Error Handling (HIGH)

• error-custom-messages - Provide custom error messages
• error-use-flatten - Use flatten() for form error display
• error-path-for-nested - Use issue.path for nested error location
• error-i18n - Implement internationalized error messages
• error-avoid-throwing-in-refine - Return false instead of throwing in refine

5. Object Schemas (MEDIUM-HIGH)

• object-strict-vs-strip - Choose strict() vs strip() for unknown keys
• object-partial-for-updates - Use partial() for update schemas
• object-pick-omit - Use pick() and omit() for schema variants
• object-extend-for-composition - Use extend() for adding fields
• object-optional-vs-nullable - Distinguish optional() from nullable()
• object-discriminated-unions - Use discriminated unions for type narrowing

6. Schema Composition (MEDIUM)

• compose-shared-schemas - Extract shared schemas into reusable modules
• compose-intersection - Use intersection() for type combinations
• compose-lazy-recursive - Use z.lazy() for recursive schemas
• compose-preprocess - Use preprocess() for data normalization
• compose-pipe - Use pipe() for multi-stage validation

7. Refinements & Transforms (MEDIUM)

• refine-vs-superrefine - Choose refine() vs superRefine() correctly
• refine-transform-coerce - Distinguish transform() from refine() and coerce()
• refine-add-path - Add path to refinement errors
• refine-defaults - Use default() for optional fields with defaults
• refine-catch - Use catch() for fault-tolerant parsing

8. Performance & Bundle (LOW-MEDIUM)

• perf-cache-schemas - Cache schema instances
• perf-zod-mini - Use Zod Mini for bundle-sensitive applications
• perf-avoid-dynamic-creation - Avoid dynamic schema creation in hot paths
• perf-lazy-loading - Lazy load large schemas
• perf-arrays - Optimize large array validation

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules
• Individual rules: references/{prefix}-{slug}.md

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

Related Skills

• For React Hook Form integration, see react-hook-form skill
• For API client generation, see orval skill

Sources

• Zod Official Documentation
• Zod v4 Release Notes
• Zod GitHub Repository
• Zod Mini
• Total TypeScript Zod Tutorial