secondsky/claude-skills / plugins/zod/skills/zod
zod
VerifiedTypeScript-first schema validation and type inference. Use for validating API requests/responses, form data, env vars, configs, defining type-safe schemas with runtime validation, transforming data, generating JSON Schema for OpenAPI/AI, or encountering missing validation errors, type inference issues, validation error handling problems. Zero dependencies, compact core (~5kb gzipped; zod/mini ~1.9kb).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 27.4 KB |
| references/advanced-patterns.md | markdown | 15.9 KB |
| references/best-practices.md | markdown | 13.9 KB |
| references/common-patterns.ts | script | 11.0 KB |
| references/ecosystem-integrations.md | markdown | 9.1 KB |
| references/error-handling.md | markdown | 12.4 KB |
| references/eslint.config.js | script | 1.6 KB |
| references/migration-guide.md | markdown | 9.2 KB |
| references/package.json | manifest | 1.0 KB |
| references/quick-reference.md | markdown | 9.5 KB |
| references/troubleshooting.md | markdown | 13.5 KB |
| references/tsconfig.json | config | 1.2 KB |
| references/type-inference.md | markdown | 10.8 KB |
references/quick-reference.md
View on GitHub# Zod Quick Reference Cheat Sheet
> **Version**: Zod 4.x (4.4.x)
> **Note**: Some APIs shown here (z.codec, z.iso.*, error helpers) are Zod 4 only
## Installation
```bash
bun add zod
# or
npm install zod
# or
pnpm add zod
# or
yarn add zod
```
## Basic Usage
```typescript
import { z } from "zod";
// Define schema
const UserSchema = z.object({
name: z.string(),
age: z.number(),
});
// Infer type
type User = z.infer<typeof UserSchema>;
// Parse (throws on error)
const user = UserSchema.parse(data);
// Safe parse (no throw)
const result = UserSchema.safeParse(data);
if (result.success) {
console.log(result.data);
} else {
console.error(result.error);
}
```
## Primitives
| Type | Code |
|------|------|
| String | `z.string()` |
| Number | `z.number()` |
| Boolean | `z.boolean()` |
| Date | `z.date()` |
| BigInt | `z.bigint()` |
| Symbol | `z.symbol()` |
| Null | `z.null()` |
| Undefined | `z.undefined()` |
| Void | `z.void()` |
| Any | `z.any()` |
| Unknown | `z.unknown()` |
| Never | `z.never()` |
## String Validators
| Validator | Code |
|-----------|------|
| Email | `z.email()` |
| URL | `z.url()` |
| UUID | `z.uuid()` |
| Min length | `z.string().min(5)` |
| Max length | `z.string().max(100)` |
| Exact length | `z.string().length(10)` |
| Regex | `z.string().regex(/pattern/)` |
| Starts with | `z.string().startsWith("pre")` |
| Ends with | `z.string().endsWith("suf")` |
| Trim | `z.string().trim()` |
| Lowercase | `z.string().toLowerCase()` |
| Uppercase | `z.string().toUpperCase()` |
## Number Validators
| Validator | Code |
|-----------|------|
| Integer | `z.number().int()` |
| Positive | `z.number().positive()` |
| Non-negative | `z.number().nonnegative()` |
| Negative | `z.number().negative()` |
| Non-positive | `z.number().nonpositive()` |
| Min | `z.number().min(0)` |
| Max | `z.number().max(100)` |
| Greater than | `z.number().gt(0)` |
| Greater/equal | `z.number().gte(0)` |
| Less than | `z.number().lt(100)` |
| Less/equal | `z.number().lte(100)` |
| Multiple of | `z.number().multipleOf(5)` |
## Collections
| Type | Code |
|------|------|
| Array | `z.array(z.string())` |
| Tuple | `z.tuple([z.string(), z.number()])` |
| Object | `z.object({ name: z.string() })` |
| Record | `z.record(z.string(), z.number())` |
| Map | `z.map(z.string(), z.number())` |
| Set | `z.set(z.string())` |
## Special Types
| Type | Code |
|------|------|
| Enum | `z.enum(["a", "b", "c"])` |
| Literal | `z.literal("value")` |
| Union | `z.union([z.string(), z.number()])` |
| Discriminated Union | `z.discriminatedUnion("type", [...])` |
| Intersection | `z.intersection(schema1, schema2)` |
## Modifiers
| Modifier | Code |
|----------|------|
| Optional | `.optional()` |
| Nullable | `.nullable()` |
| Nullish | `.nullish()` |
| Default | `.default(value)` |
| Prefault (v4) | `.prefault(value)` (pre-parse default) |
| Exact Optional (v4) | `z.exactOptional(z.string())` |
| Catch | `.catch(fallback)` |
| Readonly | `.readonly()` |
| Brand | `.brand<"BrandName">()` |
## Object Methods
| Method | Code |
|--------|------|
| Extend | `.extend({ field: z.string() })` |
| Safe Extend | `.safeExtend({ field: z.string() })` |
| Pick | `.pick({ name: true })` |
| Omit | `.omit({ age: true })` |
| Partial | `.partial()` (or `.partial({ age: true })`) |
| Required | `.required()` |
| Catchall | `.catchall(z.number())` |
| Keyof | `.keyof()` |
| Merge (deprecated) | `.merge(other)` — use `.extend(other.shape)` |
**Note**: `.deepPartial()` was removed in v4 — build recursive partials manually.
## Validation
| Method | Code |
|--------|------|
| Refine | `.refine((val) => condition, { error: "msg" })` |
| Super Refine | `.superRefine((data, ctx) => { ctx.issues.push(...) })` |
| Check (v4) | `.check(z.minLength(3), z.startsWith("a"))` |
| Transform | `.transform((val) => newVal)` |
| Pipe | `.pipe(otherSchema)` |
| Preprocess | `z.preprocess(fn, schema)` |
| Custom | `z.custom<T>(fn, { error: "msg" })` |
## Parsing
| Method | Returns | Throws? |
|--------|---------|---------|
| `.parse(data)` | `T` | Yes |
| `.safeParse(data)` | `{ success: boolean, data?: T, error?: ZodError }` | No |
| `.parseAsync(data)` | `Promise<T>` | Yes |
| `.safeParseAsync(data)` | `Promise<{...}>` | No |
## Type Inference
```typescript
// Infer output type
type User = z.infer<typeof UserSchema>;
// Get input type (for transforms)
type Input = z.input<typeof Schema>;
// Get output type (for transforms)
type Output = z.output<typeof Schema>;
```
## Error Handling
```typescript
// Flatten errors (for forms)
const flattened = z.flattenError(error);
flattened.formErrors // Top-level errors
flattened.fieldErrors // Field-specific errors
// Tree structure (for nested data)
const tree = z.treeifyError(error);
tree.errors // Current level
tree.properties // Nested errors
// Pretty print
const pretty = z.prettifyError(error);
```
## Custom Errors
```typescript
// Inline message
z.string().min(5, "Too short!");
// Error map
z.string({
error: (issue) => {
if (issue.code === "too_small") {
return `Min: ${issue.minimum}`;
}
},
});
// Per-parse override
schema.parse(data, {
error: (issue) => "Custom error",
});
```
## Coercion
```typescript
z.coerce.string() // Convert to string
z.coerce.number() // Convert to number
z.coerce.boolean() // Convert to boolean
z.coerce.bigint() // Convert to bigint
z.coerce.date() // Convert to Date
```
## Codecs
```typescript
const DateCodec = z.codec(
z.iso.datetime(),
z.date(),
{
decode: (str) => new Date(str),
encode: (date) => date.toISOString(),
}
);
DateCodec.decode("2024-01-01T00:00:00Z"); // Date
DateCodec.encode(new Date()); // string
```
## JSON Schema
```typescript
const jsonSchema = z.toJSONSchema(schema, {
target: "openapi-3.0",
cycles: "ref",
reused: "inline",
// .meta() data included by default (globalRegistry)
});
// Experimental (4.3+): JSON Schema → Zod
const schema = z.fromJSONSchema({ type: "string" });
```
## Metadata
```typescript
schema.meta({
id: "user_email",
title: "User Email",
description: "The user's email address",
});
schema.describe("User email"); // Legacy
```
## ISO Formats
```typescript
z.iso.date() // YYYY-MM-DD
z.iso.time() // HH:MM:SS
z.iso.datetime() // ISO 8601 datetime
z.iso.duration() // ISO 8601 duration
```
## Network Formats
```typescript
z.ipv4() // IPv4 address
z.ipv6() // IPv6 address
z.cidrv4() // IPv4 CIDR
z.cidrv6() // IPv6 CIDR
```
## Other Formats
```typescript
z.jwt() // JWT token
z.nanoid() // Nanoid
z.cuid() // CUID
z.cuid2() // CUID2
z.ulid() // ULID
z.base64() // Base64
z.hex() // Hexadecimal
z.guid() // Permissive UUID/GUID
z.httpUrl() // http/https URL only
z.e164() // Phone (E.164)
z.hash("sha256") // Hash of algorithm-specific length
z.uuidv4() // Version-specific UUID (also z.uuidv7)
```
## Zod Mini (`zod/mini`)
Functional, tree-shakable API (~1.9kb) for bundle-sensitive targets:
```typescript
import { z } from "zod/mini";
// Checks attach via .check() with standalone check factories
const Name = z.string().check(z.minLength(1), z.maxLength(100));
const Email = z.pipe(z.string(), z.email());
const User = z.object({ name: Name, email: Email });
z.safeParse(User, { name: "a", email: "a@b.c" }); // functional parse
// Functional wrappers live here: z.pick(schema, mask), z.omit, z.partial,
// z.keyof, z.catchall(schema, z.string()), z.optional, z.union, ...
// NOTE: z.pipe(schema, z.minLength(3)) crashes — bare checks go in .check(), not pipe
```
## Common Patterns
### Environment Variables
```typescript
const EnvSchema = z.object({
NODE_ENV: z.enum(["development", "production"]),
PORT: z.coerce.number().default(3000),
DATABASE_URL: z.url(),
});
const env = EnvSchema.parse(process.env);
```
### API Request
```typescript
const CreateUserRequest = z.object({
username: z.string().min(3).max(20),
email: z.email(),
password: z.string().min(8),
});
const result = CreateUserRequest.safeParse(req.body);
```
### Form Validation
```typescript
const FormSchema = z.object({
email: z.email({ error: "Invalid email" }),
password: z.string().min(8, "Too short"),
});
```
### Discriminated Union
```typescript
const Response = z.discriminatedUnion("status", [
z.object({ status: z.literal("success"), data: z.any() }),
z.object({ status: z.literal("error"), message: z.string() }),
]);
```
### Recursive Type
```typescript
interface Node {
value: string;
children: Node[];
}
const NodeSchema: z.ZodType<Node> = z.lazy(() =>
z.object({
value: z.string(),
children: z.array(NodeSchema),
})
);
```
## Performance Tips
1. Use `z.discriminatedUnion()` instead of `z.union()` when possible
2. Cache schema instances (define at module level)
3. Use `.safeParse()` over `.parse()` to avoid try-catch overhead
4. Lazy load large schemas with `z.lazy()`
5. Use coercion sparingly
## Common Mistakes
❌ Don't recreate schemas on every request
✅ Define schemas at module level
❌ Don't use `.refine()` for transformations
✅ Use `.transform()` for data modifications
❌ Don't ignore TypeScript strict mode
✅ Enable `"strict": true` in tsconfig.json
❌ Don't use `.parse()` for user input without error handling
✅ Use `.safeParse()` and check `result.success`
## Resources
- **Official Docs**: https://zod.dev
- **GitHub**: https://github.com/colinhacks/zod
- **Playground**: https://zod-playground.vercel.app
- **Ecosystem**: https://zod.dev/ecosystem
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |