Zod best practices

Use when authoring or reviewing handwritten Zod schemas for HTTP inputs, search params, server payloads, environment variables, or other untrusted JSON in TypeScript.

Where to validate

• Validate at trust boundaries: route handlers, server functions, webhook bodies, CLI args, and env at process start.
• Prefer one schema per boundary and reuse composed schemas (pick, omit, extend, unions) instead of duplicating shapes.

Types from schemas

• Derive TypeScript types with z.infer<typeof schema> (or z.input / z.output when you use transforms) so runtime and compile time stay aligned.
• Keep the schema as the source of truth; avoid maintaining separate handwritten runtime validation and static type shapes.

Parse vs safeParse

• Use .parse() when invalid data is exceptional and should fail fast (or when a framework maps Zod errors to 400 responses).
• Use .safeParse() when you want to branch, log, or return user-facing errors without throwing (CLI, optional fields, gradual migration).