AGENT SKILL

zod-v4

Zod 4 schema patterns and API differences from Zod 3. Activate when writing or reviewing Zod schemas, validation logic, or inferred types. Zod 4 has breaking changes from Zod 3.

License 许可
MIT
最近更新
2026-10-23
Stars
★ 1
Forks
0

01 前言 Front Matter

name
zod-v4
description
Zod 4 schema patterns and API differences from Zod 3. Activate when writing or reviewing Zod schemas, validation logic, or inferred types. Zod 4 has breaking changes from Zod 3.

03 SKILL.md 正文

Zod v4 Patterns

This project uses Zod 4 (zod@^4.x). The API has meaningful breaking changes from Zod 3. Do not guess — use the patterns below.

Breaking Changes vs Zod 3

Feature Zod 3 Zod 4
Error map z.ZodError .format() Use .issues directly or z.prettifyError(err)
.merge() Available on object Use .extend() instead
z.string().email() Built-in Built-in (unchanged)
z.object().partial() .partial() .partial() (unchanged)
z.infer<> z.infer<typeof schema> Same (unchanged)
z.input<> z.input<typeof schema> Same (unchanged)
Coercion z.coerce.string() Same (unchanged)
JSON type Not built-in z.json() — native JSON type
Template literals Not available z.templateLiteral()
z.string().check() Not available Use .check() for custom refinements

Core Patterns

Always export schema + inferred type together

// src/services/products/schemas/productSchema.ts
import { z } from 'zod';

export const productSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(1).max(200),
  price: z.number().positive(),
  category: z.enum(['electronics', 'clothing', 'food']),
});

export type Product = z.infer<typeof productSchema>;

Prefer .extend() over .merge()

// BAD (Zod 3 style, .merge() may behave differently)
const extendedSchema = baseSchema.merge(z.object({ extra: z.string() }));

// GOOD
const extendedSchema = baseSchema.extend({ extra: z.string() });

Use z.prettifyError() for human-readable errors

// BAD
const message = error.format(); // Zod 3 API — may not exist

// GOOD
import { z } from 'zod';
const result = schema.safeParse(input);
if (!result.success) {
  console.error(z.prettifyError(result.error));
}

Use .safeParse() at system boundaries, .parse() internally

// At API/form boundary — recoverable
const result = schema.safeParse(rawInput);
if (!result.success) return { error: z.prettifyError(result.error) };
const data = result.data;

// Internally when data is already validated upstream — throw on invalid
const data = schema.parse(knownValidInput);

Use z.json() for arbitrary JSON values

// BAD (Zod 3 workaround)
const jsonSchema: z.ZodType = z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(z.lazy(() => jsonSchema)), z.record(z.lazy(() => jsonSchema))]);

// GOOD (Zod 4 native)
const metadataSchema = z.object({
  id: z.string(),
  extra: z.json(), // accepts any JSON-serializable value
});

Use z.templateLiteral() for string patterns

// GOOD (Zod 4 feature)
const routeSchema = z.templateLiteral(['/products/', z.string().uuid()]);
// matches: '/products/123e4567-e89b-12d3-a456-426614174000'

API response validation in service layer

Validate API responses at the service boundary, not in components.

// src/services/products/api.ts
import { z } from 'zod';
import { productSchema } from './schemas/productSchema';
import { http } from '@/lib/@http';

const productsResponseSchema = z.array(productSchema);

export const getProducts = async (): Promise<Product[]> => {
  const raw = await http.get('products').json();
  return productsResponseSchema.parse(raw); // throws if API shape changed
};

Form schemas with .omit() / .pick()

const createProductSchema = productSchema.omit({ id: true });
export type CreateProductInput = z.infer<typeof createProductSchema>;

const updateProductSchema = productSchema.pick({ name: true, price: true }).partial();
export type UpdateProductInput = z.infer<typeof updateProductSchema>;

Refinements with .check() (Zod 4)

// Zod 4 — use .check() for custom validations
const passwordSchema = z.string()
  .min(8)
  .check((val, ctx) => {
    if (!/[A-Z]/.test(val)) {
      ctx.addIssue({ message: 'Must contain an uppercase letter' });
    }
  });

Naming Conventions (project-specific)

  • File: <name>Schema.ts (e.g., productSchema.ts)
  • Export: export const <name>Schema = z.object({...})
  • Type: export type <Name> = z.infer<typeof <name>Schema>
  • Keep schema and type in the same file — co-location is required

04 同仓库更多 Skills

Phenomenon-Studio
Phenomenon-Studio/phenomenon-configs

web-security

Enforce web security and avoid security vulnerabilities.

★ 1
Phenomenon-Studio
Phenomenon-Studio/phenomenon-configs

typescript

Write clean, efficient TypeScript code that follows project conventions and advanced type patterns. Use when writing or reviewing TypeScript code, defining types, creating generics, handling errors, or working with React components, Zod schemas, and TanStack libraries.

★ 1
Phenomenon-Studio
Phenomenon-Studio/phenomenon-configs

tanstack-router

TanStack Router patterns for this repo — file-based routing, auth guards, search params, data loading, TanStack Query integration, navigation, and code splitting. Use when creating routes, adding pages, implementing auth flows, working with search/path params, or integrating loaders with TanStack Query.

★ 1
Phenomenon-Studio
Phenomenon-Studio/phenomenon-configs

tanstack-query

TanStack Query patterns for this repo — queryOptions/mutationOptions factories, query key hierarchies, service layer integration, optimistic updates, Suspense usage, error handling, and TanStack Router data loading. Use when creating queries, mutations, API services, query keys, cache invalidation, optimistic updates, or integrating data fetching with routes.

★ 1
Phenomenon-Studio
Phenomenon-Studio/phenomenon-configs

tanstack-form

Build forms using TanStack Form with the project's useAppForm composition, composable field components, Zod validation schemas, FormFieldWrapper error tracking, and form.AppField vs form.Field patterns. Use when creating new forms, adding form fields, writing form validation, or working with TanStack Form in this project.

★ 1
Phenomenon-Studio
Phenomenon-Studio/phenomenon-configs

react

Build clean, modern React components that apply common best practices and avoid common pitfalls like unnecessary state management or useEffect usage.

★ 1