zod-skill: Instructions file for Codex

Zod: compiled rules

Every rule in rules/, expanded, for agents that read one file. Source: SKILL.md and rules/*.md. Baseline: zod ^4.6.0, checked against zod 4.6.7. Skill version 2.0.0.

Abstract

Zod is for runtime type validation — parsing untrusted data at system boundaries (API input, form data, env vars, external services). For compile-time-only types, plain TypeScript is sufficient.

Table of Contents

1. Parsing & Type Safety — CRITICAL
2. Schema Design — CRITICAL
3. Refinements & Transforms — HIGH
4. Error Handling — HIGH
5. Performance & Composition — MEDIUM
6. v4 Migration — MEDIUM
7. Advanced Patterns — MEDIUM
8. Architecture & Boundaries — CRITICAL/HIGH
9. Observability — HIGH/MEDIUM

1. Parsing & Type Safety

Impact: CRITICAL

Use safeParse() for User Input

parse-use-safeParse · CRITICAL · Use safeParse() instead of parse() to avoid throwing on invalid input.

Problem

parse() throws a ZodError on invalid input. Wrapping it in try/catch is verbose and error-prone — you lose the discriminated success/error result and risk catching unrelated errors.

Incorrect

const UserSchema = z.object({ name: z.string(), email: z.email() })

// BUG: try/catch is verbose and catches unrelated errors
function validateInput(data: unknown) {
  try {
    const result = UserSchema.parse(data)
    return { success: true, data: result }
  } catch (e) {
    if (e instanceof z.ZodError) {
      return { success: false, errors: e.issues }
    }
    throw e // rethrow non-Zod errors
  }
}

Correct

function validateInput(data: unknown) {
  const result = UserSchema.safeParse(data)
  if (!result.success) {
    return { success: false, errors: result.error.issues }
  }
  return { success: true, data: result.data }
}