zod

Files (49)

• AGENTS.md
• README.md
• SKILL.md
• _template.md · assets/templates/
• metadata.json
• _sections.md · references/
• compose-intersection.md · references/
• compose-lazy-recursive.md · references/
• compose-pipe.md · references/
• compose-preprocess.md · references/
• compose-shared-schemas.md · references/
• error-avoid-throwing-in-refine.md · references/
• error-custom-messages.md · references/
• error-i18n.md · references/
• error-path-for-nested.md · references/
• error-use-flatten.md · references/
• object-discriminated-unions.md · references/
• object-extend-for-composition.md · references/
• object-optional-vs-nullable.md · references/
• object-partial-for-updates.md · references/
• object-pick-omit.md · references/
• object-strict-vs-strip.md · references/
• parse-async-for-async-refinements.md · references/
• parse-avoid-double-validation.md · references/
• parse-handle-all-issues.md · references/
• parse-never-trust-json.md · references/
• parse-use-safeparse.md · references/
• parse-validate-early.md · references/
• perf-arrays.md · references/
• perf-avoid-dynamic-creation.md · references/
• perf-cache-schemas.md · references/
• perf-lazy-loading.md · references/
• perf-zod-mini.md · references/
• refine-add-path.md · references/
• refine-catch.md · references/
• refine-defaults.md · references/
• refine-transform-coerce.md · references/
• refine-vs-superrefine.md · references/
• schema-avoid-optional-abuse.md · references/
• schema-coercion-for-form-data.md · references/
• schema-string-validations.md · references/
• schema-use-enums.md · references/
• schema-use-primitives-correctly.md · references/
• schema-use-unknown-not-any.md · references/
• type-branded-types.md · references/
• type-enable-strict-mode.md · references/
• type-export-schemas-and-types.md · references/
• type-input-vs-output.md · references/
• type-use-z-infer.md · references/

SKILL.md (first lines)

# 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](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - 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](https://zod.dev/)
- [Zod v4 Release Notes](https://zod.dev/v4)

From pproenca/dot-skills, MIT.

More from pproenca/dot-skills