Referencia de la API de Zod

Zod es una librería de declaración y validación de schemas basada en TypeScript. Esto te permite definir schemas que puedes usar para validar datos y transformar datos, desde un tipo simple (ej. string, number) hasta estructuras de datos complejas (ej. objetos anidados).

El módulo astro/zod expone una re-exportación de Zod que te da acceso a todas las características de Zod v4. Al usar este módulo, no necesitas instalar Zod tú mismo. Esto también asegura que tu proyecto use las mismas versiones de API que Astro al usar características como Content Collections o Actions.

Visita el sitio web de Zod para la documentación completa sobre cómo funciona Zod y qué características están disponibles.

Importaciones desde astro/zod

import { z } from 'astro/zod';

z

Type: object

La utilidad z te da acceso a validadores para una amplia gama de tipos de datos, métodos y tipos para trabajar con tus datos.

Aprende más sobre la utilidad z en la documentación de Zod

Validadores de tipos de datos comunes

Con Zod, puedes validar cualquier tipo de dato, como primitivos, objetos, arrays y más.

El siguiente ejemplo muestra un cheatsheet de muchos tipos de datos comunes de Zod para crear un schema de user:

import { z } from 'astro/zod';

const user = z.object({
  username: z.string(),
  name: z.string().min(2),
  email: z.email(),
  role: z.enum(["admin", "editor"]),
  language: z.enum(["en", "fr", "es"]).default("en"),
  hobbies: z.array(z.string()),
  age: z.number(),
  isEmailConfirmed: z.boolean(),
  inscriptionDate: z.date(),
  website: z.url().optional(),
});

Extraer un tipo de TypeScript

Zod te permite crear un tipo de TypeScript desde cualquier schema usando la inferencia de tipos de Zod. Esto puede ser útil para describir una estructura de datos esperada al definir props de componentes.

El siguiente ejemplo crea un tipo User basado en el schema anterior:

type User = z.infer<typeof user>;

/* The `User` type will be:
 * type User = {
 *   username: string;
 *   name: string;
 *   email: string;
 *   role: "admin" | "editor";
 *   language: "en" | "fr" | "es";
 *   hobbies: string[];
 *   age: number;
 *   isEmailConfirmed: boolean;
 *   inscriptionDate: Date;
 *   website?: string | undefined;
 * }
 */

Usar métodos de Zod

Zod proporciona varios métodos de schema para personalizar mensajes de error, transformar datos, o crear lógicas de validación personalizadas.

// Customize the error message
const nonEmptyStrings = z.array(z.string()).nonempty("Can't be empty!");

// Validate a data from a schema
nonEmptyStrings.parse([]); // will throws our custom error

// Create an object from a URL for a decorative img
const decorativeImg = z.string().transform((value) => {
  return { src: value, alt: "" };
});

// Create a custom validator and error message for a string
const constrainedString = z
  .string()
  .refine((val) => val.length > 0 && val.length <= 255, {
    error: "Must be between 1 and 255 characters.",
  });

Importaciones individuales

Alternativamente, puedes importar todos los validadores, métodos y tipos de Zod disponibles en la utilidad z directamente desde el módulo.

El siguiente ejemplo importa coerce para crear un objeto Date desde un string de fecha:

import { coerce } from 'astro/zod';

const publishedOn = coerce.date();
const publicationDate = publishedOn.parse("2025-12-03");