仓库原始内容
按源仓库内容呈现，保留标题、案例、代码、表格、链接以及原文引用的演示图片。
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 typeschema-use-unknown-not-any- Use z.unknown() instead of z.any() for type safetyschema-avoid-optional-abuse- Avoid overusing optional fieldsschema-string-validations- Apply string validations at schema definitionschema-use-enums- Use enums for fixed string valuesschema-coercion-for-form-data- Use coercion for form and query data
2. Parsing & Validation (CRITICAL)
parse-use-safeparse- Use safeParse() for user inputparse-async-for-async-refinements- Use parseAsync for async refinementsparse-handle-all-issues- Handle all validation issues not just firstparse-validate-early- Validate at system boundariesparse-avoid-double-validation- Avoid validating same data twiceparse-never-trust-json- Never trust JSON.parse output
3. Type Inference (HIGH)
type-use-z-infer- Use z.infer instead of manual typestype-input-vs-output- Distinguish z.input from z.infer for transformstype-export-schemas-and-types- Export both schemas and inferred typestype-branded-types- Use branded types for domain safetytype-enable-strict-mode- Enable TypeScript strict mode
4. Error Handling (HIGH)
error-custom-messages- Provide custom error messageserror-use-flatten- Use flatten() for form error displayerror-path-for-nested- Use issue.path for nested error locationerror-i18n- Implement internationalized error messageserror-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 keysobject-partial-for-updates- Use partial() for update schemasobject-pick-omit- Use pick() and omit() for schema variantsobject-extend-for-composition- Use extend() for adding fieldsobject-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 modulescompose-intersection- Use intersection() for type combinationscompose-lazy-recursive- Use z.lazy() for recursive schemascompose-preprocess- Use preprocess() for data normalizationcompose-pipe- Use pipe() for multi-stage validation
7. Refinements & Transforms (MEDIUM)
refine-vs-superrefine- Choose refine() vs superRefine() correctlyrefine-transform-coerce- Distinguish transform() from refine() and coerce()refine-add-path- Add path to refinement errorsrefine-defaults- Use default() for optional fields with defaultsrefine-catch- Use catch() for fault-tolerant parsing
8. Performance & Bundle (LOW-MEDIUM)
perf-cache-schemas- Cache schema instancesperf-zod-mini- Use Zod Mini for bundle-sensitive applicationsperf-avoid-dynamic-creation- Avoid dynamic schema creation in hot pathsperf-lazy-loading- Lazy load large schemasperf-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-formskill - For API client generation, see
orvalskill
