zod

Zod Cursor Rules

You are an expert in Zod schema validation. Follow these rules:

Schema Design

• Define schemas as the single source of truth — infer TypeScript types with z.infer
• Never duplicate types manually when a Zod schema exists
• Colocate schemas with their usage (API route, form, etc.)
• Name schemas with Schema suffix: UserSchema, CreatePostSchema
• Export both the schema and inferred type together

Primitives & Modifiers

• Use z.string().min(1) instead of z.string() for required strings — empty string passes z.string()
• Use z.coerce.number() for form inputs and query params, not z.number()
• Prefer z.literal() for exact values over z.enum() with one member
• Use z.discriminatedUnion() over z.union() when objects share a type/kind field — better errors and performance

Transforms & Pipes

• Use .transform() to normalize data at parse time (trim strings, lowercase emails)
• Chain .pipe() for multi-step validation: parse string → coerce to number → validate range
• Never mutate input inside .transform() — always return new values
• Keep transforms pure — no side effects, no API calls inside .transform()

Refinements

• Use .refine() for single-field custom validation with a clear error message
• Use .superRefine() for cross-field validation (password confirmation, date ranges)
• Always provide a message parameter — default Zod errors are unhelpful to users
• Set the path in superRefine errors to attach them to specific fields

Error Handling

• Use schema.safeParse() in API routes — never let .parse() throw unhandled
• Format errors with z.ZodError.flatten() for form-friendly { fieldErrors, formErrors }
• Map Zod errors to user-facing messages — don't expose raw Zod error strings
• Create a shared parseOrThrow utility that wraps safeParse with consistent error responses

Anti-Patterns — Do NOT

• ❌ z.any() or z.unknown() without immediately piping into a real schema
• ❌ Wrapping Zod schemas in try/catch when safeParse exists
• ❌ Using .optional() when you mean .nullable() — they're different
• ❌ Defining schemas inside components or functions — define at module level
• ❌ Skipping .strip() or .strict() — pick one. Default (strip) is usually correct for APIs
• ❌ Using z.object().merge() when .extend() works — merge creates a new ZodObject, extend inherits