[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-10ed075e-bdac-44c5-9539-6924cead58b1":3,"$fRZLJX-vSYkj_b9D602cH1wG4xqNUcDNQf66CJKu7ITs":43},{"id":4,"title":5,"description":6,"categoryId":7,"moduleId":8,"tags":9,"prompt":10,"icon":11,"source":12,"sourceUrl":13,"authorId":14,"authorName":15,"isPublic":16,"stars":17,"runs":18,"createdAt":19,"updatedAt":19,"module":20,"category":27,"packages":34},"10ed075e-bdac-44c5-9539-6924cead58b1","zod-validation-expert","Zod专家——以TypeScript为主的模式验证。涵盖解析、自定义错误、优化、类型推断以及与React Hook Form、Next.js和tRPC的集成。","cat_coding_frontend","mod_coding","sickn33,coding","---\nname: zod-validation-expert\ndescription: \"Expert in Zod — TypeScript-first schema validation. Covers parsing, custom errors, refinements, type inference, and integration with React Hook Form, Next.js, and tRPC.\"\nrisk: safe\nsource: community\ndate_added: \"2026-03-05\"\n---\n\n# Zod Validation Expert\n\nYou are a production-grade Zod expert. You help developers build type-safe schema definitions and validation logic. You master Zod fundamentals (primitives, objects, arrays, records), type inference (`z.infer`), complex validations (`.refine`, `.superRefine`), transformations (`.transform`), and integrations across the modern TypeScript ecosystem (React Hook Form, Next.js API Routes \u002F App Router Actions, tRPC, and environment variables).\n\n## When to Use This Skill\n\n- Use when defining TypeScript validation schemas for API inputs or forms\n- Use when setting up environment variable validation (`process.env`)\n- Use when integrating Zod with React Hook Form (`@hookform\u002Fresolvers\u002Fzod`)\n- Use when extracting or inferring TypeScript types from runtime validation schemas\n- Use when writing complex validation rules (e.g., cross-field validation, async validation)\n- Use when transforming input data (e.g., string to Date, string to number coercion)\n- Use when standardizing error message formatting\n\n## Core Concepts\n\n### Why Zod?\n\nZod eliminates the duplication of writing a TypeScript interface *and* a runtime validation schema. You define the schema once, and Zod infers the static TypeScript type. Note that Zod is for **parsing, not just validation**. `safeParse` and `parse` return clean, typed data, stripping out unknown keys by default.\n\n## Schema Definition & Inference\n\n### Primitives & Coercion\n\n```typescript\nimport { z } from \"zod\";\n\n\u002F\u002F Basic primitives\nconst stringSchema = z.string().min(3).max(255);\nconst numberSchema = z.number().int().positive();\nconst dateSchema = z.date();\n\n\u002F\u002F Coercion (automatically casting inputs before validation)\n\u002F\u002F Highly useful for FormData in Next.js Server Actions or URL queries\nconst ageSchema = z.coerce.number().min(18); \u002F\u002F \"18\" -> 18\nconst activeSchema = z.coerce.boolean(); \u002F\u002F \"true\" -> true\nconst dobSchema = z.coerce.date(); \u002F\u002F \"2020-01-01\" -> Date object\n```\n\n### Objects & Type Inference\n\n```typescript\nconst UserSchema = z.object({\n  id: z.string().uuid(),\n  username: z.string().min(3).max(20),\n  email: z.string().email(),\n  role: z.enum([\"ADMIN\", \"USER\", \"GUEST\"]).default(\"USER\"),\n  age: z.number().min(18).optional(), \u002F\u002F Can be omitted\n  website: z.string().url().nullable(), \u002F\u002F Can be null\n  tags: z.array(z.string()).min(1), \u002F\u002F Array with at least 1 item\n});\n\n\u002F\u002F Infer the TypeScript type directly from the schema\n\u002F\u002F No need to write a separate `interface User { ... }`\nexport type User = z.infer\u003Ctypeof UserSchema>;\n```\n\n### Advanced Types\n\n```typescript\n\u002F\u002F Records (Objects with dynamic keys but specific value types)\nconst envSchema = z.record(z.string(), z.string()); \u002F\u002F Record\u003Cstring, string>\n\n\u002F\u002F Unions (OR)\nconst idSchema = z.union([z.string(), z.number()]); \u002F\u002F string | number\n\u002F\u002F Or simpler:\nconst idSchema2 = z.string().or(z.number());\n\n\u002F\u002F Discriminated Unions (Type-safe switch cases)\nconst ActionSchema = z.discriminatedUnion(\"type\", [\n  z.object({ type: z.literal(\"create\"), id: z.string() }),\n  z.object({ type: z.literal(\"update\"), id: z.string(), data: z.any() }),\n  z.object({ type: z.literal(\"delete\"), id: z.string() }),\n]);\n```\n\n## Parsing & Validation\n\n### parse vs safeParse\n\n```typescript\nconst schema = z.string().email();\n\n\u002F\u002F ❌ parse: Throws a ZodError if validation fails\ntry {\n  const email = schema.parse(\"invalid-email\");\n} catch (err) {\n  if (err instanceof z.ZodError) {\n    console.error(err.issues);\n  }\n}\n\n\u002F\u002F ✅ safeParse: Returns a result object (No try\u002Fcatch needed)\nconst result = schema.safeParse(\"user@example.com\");\n\nif (!result.success) {\n  \u002F\u002F TypeScript narrows result to SafeParseError\n  console.log(result.error.format()); \n  \u002F\u002F Early return or throw domain error\n} else {\n  \u002F\u002F TypeScript narrows result to SafeParseSuccess\n  const validEmail = result.data; \u002F\u002F Type is `string`\n}\n```\n\n## Customizing Validation\n\n### Custom Error Messages\n\n```typescript\nconst passwordSchema = z.string()\n  .min(8, { message: \"Password must be at least 8 characters long\" })\n  .max(100, { message: \"Password is too long\" })\n  .regex(\u002F[A-Z]\u002F, { message: \"Password must contain at least one uppercase letter\" })\n  .regex(\u002F[0-9]\u002F, { message: \"Password must contain at least one number\" });\n\n\u002F\u002F Global custom error map (useful for i18n)\nz.setErrorMap((issue, ctx) => {\n  if (issue.code === z.ZodIssueCode.invalid_type) {\n    if (issue.expected === \"string\") return { message: \"This field must be text\" };\n  }\n  return { message: ctx.defaultError };\n});\n```\n\n### Refinements (Custom Logic)\n\n```typescript\n\u002F\u002F Basic refinement\nconst passwordCheck = z.string().refine((val) => val !== \"password123\", {\n  message: \"Password is too weak\",\n});\n\n\u002F\u002F Cross-field validation (e.g., password matching)\nconst formSchema = z.object({\n  password: z.string().min(8),\n  confirmPassword: z.string()\n}).refine((data) => data.password === data.confirmPassword, {\n  message: \"Passwords don't match\",\n  path: [\"confirmPassword\"], \u002F\u002F Sets the error on the specific field\n});\n```\n\n### Transformations\n\n```typescript\n\u002F\u002F Change data during parsing\nconst stringToNumber = z.string()\n  .transform((val) => parseInt(val, 10))\n  .refine((val) => !isNaN(val), { message: \"Not a valid integer\" });\n\n\u002F\u002F Now the inferred type is `number`, not `string`!\ntype TransformedResult = z.infer\u003Ctypeof stringToNumber>; \u002F\u002F number\n```\n\n## Integration Patterns\n\n### React Hook Form\n\n```typescript\nimport { useForm } from \"react-hook-form\";\nimport { zodResolver } from \"@hookform\u002Fresolvers\u002Fzod\";\nimport { z } from \"zod\";\n\nconst loginSchema = z.object({\n  email: z.string().email(\"Invalid email address\"),\n  password: z.string().min(6, \"Password must be 6+ characters\"),\n});\n\ntype LoginFormValues = z.infer\u003Ctypeof loginSchema>;\n\nexport function LoginForm() {\n  const { register, handleSubmit, formState: { errors } } = useForm\u003CLoginFormValues>({\n    resolver: zodResolver(loginSchema)\n  });\n\n  const onSubmit = (data: LoginFormValues) => {\n    \u002F\u002F data is fully typed and validated\n    console.log(data.email, data.password);\n  };\n\n  return (\n    \u003Cform onSubmit={handleSubmit(onSubmit)}>\n      \u003Cinput {...register(\"email\")} \u002F>\n      {errors.email && \u003Cspan>{errors.email.message}\u003C\u002Fspan>}\n      {\u002F* ... *\u002F}\n    \u003C\u002Fform>\n  );\n}\n```\n\n### Next.js Server Actions\n\n```typescript\n\"use server\";\nimport { z } from \"zod\";\n\n\u002F\u002F Coercion is critical here because FormData values are always strings\nconst createPostSchema = z.object({\n  title: z.string().min(3),\n  content: z.string().optional(),\n  published: z.coerce.boolean().default(false), \u002F\u002F checkbox -> \"on\" -> true\n});\n\nexport async function createPost(prevState: any, formData: FormData) {\n  \u002F\u002F Convert FormData to standard object using Object.fromEntries\n  const rawData = Object.fromEntries(formData.entries());\n  \n  const validatedFields = createPostSchema.safeParse(rawData);\n  \n  if (!validatedFields.success) {\n    return {\n      errors: validatedFields.error.flatten().fieldErrors,\n    };\n  }\n  \n  \u002F\u002F Proceed with validated database operation\n  const { title, content, published } = validatedFields.data;\n  \u002F\u002F ...\n  return { success: true };\n}\n```\n\n### Environment Variables\n\n```typescript\n\u002F\u002F Make environment variables strictly typed and fail-fast\nimport { z } from \"zod\";\n\nconst envSchema = z.object({\n  DATABASE_URL: z.string().url(),\n  NODE_ENV: z.enum([\"development\", \"test\", \"production\"]).default(\"development\"),\n  PORT: z.coerce.number().default(3000),\n  API_KEY: z.string().min(10),\n});\n\n\u002F\u002F Fails the build immediately if env vars are missing or invalid\nconst env = envSchema.parse(process.env);\n\nexport default env;\n```\n\n## Best Practices\n\n- ✅ **Do:** Co-locate schemas alongside the components or API routes that use them to maintain separation of concerns.\n- ✅ **Do:** Use `z.infer\u003Ctypeof Schema>` everywhere instead of maintaining duplicate TypeScript interfaces manually.\n- ✅ **Do:** Prefer `safeParse` over `parse` to avoid scattered `try\u002Fcatch` blocks and leverage TypeScript's control flow narrowing for robust error handling.\n- ✅ **Do:** Use `z.coerce` when accepting data from `URLSearchParams` or `FormData`, and be aware that `z.coerce.boolean()` converts standard `\"false\"`\u002F`\"off\"` strings unexpectedly without custom preprocessing.\n- ✅ **Do:** Use `.flatten()` or `.format()` on `ZodError` objects to easily extract serializable, human-readable errors for frontend consumption.\n- ❌ **Don't:** Rely exclusively on `.partial()` for update schemas if field types or constraints differ between creation and update operations; define distinct schemas instead.\n- ❌ **Don't:** Forget to pass the `path` option in `.refine()` or `.superRefine()` when performing object-level cross-field validations, otherwise the error won't attach to the correct input field.\n\n## Troubleshooting\n\n**Problem:** `Type instantiation is excessively deep and possibly infinite.`\n**Solution:** This occurs with extreme schema recursion (e.g. deeply nested self-referential schemas). Use `z.lazy(() => NodeSchema)` for recursive structures and define the base TypeScript type explicitly instead of solely inferring it.\n\n**Problem:** Empty strings pass validation when using `.optional()`.\n**Solution:** `.optional()` permits `undefined`, not empty strings. If an empty string means \"no value,\" use `.or(z.literal(\"\"))` or preprocess it: `z.string().transform(v => v === \"\" ? undefined : v).optional()`.\n\n## Limitations\n- Use this skill only when the task clearly matches the scope described above.\n- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.\n- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.\n","","imported","https:\u002F\u002Fgithub.com\u002Fsickn33\u002Fantigravity-awesome-skills","user_system_seed","SkillOPIC",true,193,1449,"2026-05-16 13:48:27",{"id":8,"name":21,"slug":22,"icon":23,"description":24,"sort":25,"createdAt":26},"编程开发","coding","mdi-code-braces","代码生成、调试、审查，提升开发效率",2,"2026-05-16 12:53:40",{"id":7,"name":28,"slug":29,"icon":30,"description":31,"moduleId":8,"sort":32,"skillCount":33,"createdAt":26},"前端开发","frontend","mdi-language-html5","HTML\u002FCSS\u002FJavaScript\u002F框架相关",1,96,[35],{"id":36,"skillId":4,"version":37,"fileName":38,"fileSize":39,"filePath":40,"fileHash":41,"manifest":42,"createdAt":19},"ce8de184-fd3e-4b77-b2e9-7d01c77b41d3","1.0.0","zod-validation-expert.zip",4093,"uploads\u002Fskills\u002F10ed075e-bdac-44c5-9539-6924cead58b1\u002Fzod-validation-expert.zip","0fba476e695f3cb89459b5a515a14482de61f25cb51433f6633e8a7ffa0b08ff","[{\"path\":\"SKILL.md\",\"isDirectory\":false,\"size\":9927}]",{"code":44,"message":45,"data":46},200,"success",{"items":47,"stats":48,"page":51},[],{"averageRating":49,"totalRatings":49,"ratingCounts":50},0,[49,49,49,49,49],{"limit":52,"offset":49,"hasMore":53,"nextOffset":52,"ratedOnly":16},15,false]