Référence de l'API Zod

Zod est une bibliothèque de déclaration et de validation de schémas reposant sur TypeScript. Elle vous permet de définir des schémas que vous pouvez utiliser pour valider et transformer des données, d’un type simple (par exemple string, number) à des structures de données complexes (par exemple des objets imbriqués).

Le module astro/zod expose une réexportation de Zod qui vous donne accès à toutes les fonctionnalités de Zod v3. Grâce à ce module, vous n’avez pas besoin d’installer Zod vous-même. Cela garantit également que votre projet utilise la même version des API qu’Astro lors de l’utilisation de fonctionnalités telles que les collections de contenu ou les actions.

Consultez le site web de Zod v3 pour obtenir la documentation complète sur le fonctionnement de Zod et les fonctionnalités disponibles.

Importations depuis astro/zod

import { z } from 'astro/zod';

z

Type : object

L’utilitaire z vous donne accès à des validateurs pour un large éventail de types de données, des méthodes et des types pour travailler avec vos données.

Apprenez-en plus sur l’utilitaire z dans la documentation de Zod.

Validateurs de types de données courants

Avec Zod, vous pouvez valider tout type de données, comme les primitives, les objets, les tableaux et plus encore.

L’exemple suivant présente un aide-mémoire regroupant de nombreux types de données courants avec Zod pour créer un schéma user :

import { z } from 'astro/zod';

const user = z.object({
  username: z.string(),
  name: z.string().min(2),
  email: z.string().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.string().url().optional(),
});

Extraction d’un type Typescript

Zod vous permet de créer un type Typescript à partir de n’importe quel schéma en utilisant l’inférence de type Zod. Cela peut s’avérer utile pour décrire la structure de données attendue lors de la définition des propriétés d’un composant.

L’exemple suivant crée un type User reposant sur le schéma précédent :

type User = z.infer<typeof user>;

/* Le type `User` sera :
 * 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;
 * }
 */

Utilisation des méthodes de Zod

Zod fournit diverses méthodes de schéma pour personnaliser les messages d’erreur, transformer les données ou créer des logiques de validation personnalisées.

// Personnaliser le message d'erreur
const nonEmptyStrings = z.string().array().nonempty({
  message: "Ne peut pas être vide !",
});

// Valider des données à partir d'un schéma
nonEmptyStrings.parse([]); // générera notre erreur personnalisée

// Créer un objet à partir d'une URL pour une image décorative
const decorativeImg = z.string().transform((value) => {
  return { src: value, alt: "" };
});

// Créer un validateur personnalisé et un message d'erreur pour une chaîne de caractères.
const constrainedString = z
  .string()
  .refine((val) => val.length > 0 && val.length <= 255, {
    message: "Doit contenir entre 1 et 255 caractères.",
  });

Importations individuelles

Vous pouvez également importer tous les validateurs, méthodes et types Zod disponibles dans l’utilitaire z directement depuis le module.

L’exemple suivant importe coerce pour créer un objet Date à partir d’une date sous forme de chaîne de caractères :

import { coerce } from 'astro/zod';

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