Para autores de bibliotecas

// package.json
{
  "peerDependencies": {
    "zod": "^3.25.0 || ^4.0.0"
  }
}

Esta página está destinada principalmente para el consumo de autores de bibliotecas que están construyendo herramientas sobre Zod.

¿Necesito depender de Zod?

Lo primero es lo primero, asegúrate de que necesitas depender de Zod en absoluto.

Si estás construyendo una biblioteca que acepta esquemas definidos por el usuario para realizar validación de caja negra, es posible que no necesites integrarte específicamente con Zod. En su lugar, investiga Standard Schema. Es una interfaz compartida implementada por la mayoría de las bibliotecas de validación populares en el ecosistema TypeScript (ver la lista completa), incluido Zod.

Esta especificación funciona muy bien si aceptas esquemas definidos por el usuario y los tratas como validadores de "caja negra". Dada cualquier biblioteca compatible, puedes extraer tipos de entrada/salida inferidos, validar entradas y obtener un error estandarizado.

Si necesitas funcionalidad específica de Zod, sigue leyendo.

¿Cómo configurar dependencias pares?

Cualquier biblioteca construida sobre Zod debe incluir "zod" en "peerDependencies". Esto permite que tus usuarios "traigan su propio Zod".

// package.json
{
  // ...
  "peerDependencies": {
    "zod": "^3.25.0 || ^4.0.0" // la subruta "zod/v4" se añadió en 3.25.0
  }
}

Durante el desarrollo, necesitas cumplir con tu propio requisito de dependencia par, para hacerlo, agrega "zod" a tus "devDependencies" también.

// package.json
{
  "peerDependencies": {
    "zod": "^3.25.0 || ^4.0.0"
  },
  "devDependencies": {
    // generalmente, debes desarrollar contra la última versión de Zod
    "zod": "^3.25.0 || ^4.0.0"
  }
}

¿Cómo soportar Zod 4?

Para soportar Zod 4, actualiza la versión mínima para tu dependencia par "zod" a ^3.25.0 || ^4.0.0.

// package.json
{
  // ...
  "peerDependencies": {
    "zod": "^3.25.0 || ^4.0.0"
  }
}

A partir de v3.25.0, el paquete principal de Zod 4 está disponible en la subruta "zod/v4/core". Lee el escrito sobre Versionado en Zod 4 para obtener el contexto completo sobre este enfoque de versionado.

import * as z4 from "zod/v4/core";

Importa solo desde estas subrutas. Piensa en ellas como "enlaces permanentes" a sus respectivas versiones de Zod. Estos permanecerán disponibles para siempre.

• "zod/v3" para Zod 3 ✅
• "zod/v4/core" para el paquete Zod 4 Core ✅

Generalmente no deberías importar desde ninguna otra ruta. La biblioteca Zod Core es una biblioteca compartida que sustenta tanto a Zod 4 Classic como a Zod 4 Mini. Generalmente es una mala idea implementar cualquier funcionalidad que sea específica para uno u otro. No importes desde estas subrutas:

• "zod" — ❌ En lanzamientos 3.x, esto exporta Zod 3. En lanzamientos 4.x, esto exportará Zod 4. Usa los enlaces permanentes en su lugar.
• "zod/v4" y "zod/v4/mini"— ❌ Estas subrutas son los hogares de Zod 4 Classic y Mini, respectivamente. Si quieres que tu biblioteca funcione tanto con Zod como con Zod Mini, debes construir contra las clases base definidas en "zod/v4/core". Si haces referencia a clases del módulo "zod/v4", tu biblioteca no funcionará con Zod Mini, y viceversa. Esto está extremadamente desaconsejado. Usa "zod/v4/core" en su lugar, que exporta las subclases con prefijo $ que son extendidas por Zod Classic y Zod Mini. Los componentes internos de las subclases classic y mini son idénticos; solo difieren en qué métodos auxiliares implementan.

¿Necesito publicar una nueva versión mayor?

No, no deberías necesitar publicar una nueva versión mayor de tu biblioteca para soportar Zod 4 (a menos que estés eliminando el soporte para Zod 3, lo cual no se recomienda).

Necesitarás aumentar tu dependencia par a ^3.25.0, por lo que tus usuarios necesitarán npm upgrade zod. Pero no hubo cambios disruptivos en Zod 3 entre [email protected] y [email protected]; de hecho, no hubo cambios de código en absoluto. Dado que se requerirán cambios de código por parte de tus usuarios, no creo que esto constituya un cambio disruptivo. Recomiendo no publicar una nueva versión mayor.

¿Cómo soportar Zod 3 y Zod 4 simultáneamente?

A partir de v3.25.0, el paquete contiene copias de tanto Zod 3 como Zod 4 en sus respectivas subrutas. Esto facilita el soporte de ambas versiones simultáneamente.

import * as z3 from "zod/v3";
import * as z4 from "zod/v4/core";
 
type Schema = z3.ZodTypeAny | z4.$ZodType;
 
function acceptUserSchema(schema: z3.ZodTypeAny | z4.$ZodType) {
  // ...
}

Para diferenciar entre esquemas de Zod 3 y Zod 4 en tiempo de ejecución, verifica la propiedad "_zod". Esta propiedad solo está definida en esquemas de Zod 4.

import type * as z3 from "zod/v3";
import type * as z4 from "zod/v4/core";
 
declare const schema: z3.ZodTypeAny | z4.$ZodType;
 
if ("_zod" in schema) {
  schema._zod.def; // esquema Zod 4
} else {
  schema._def; // esquema Zod 3
}

¿Cómo soportar Zod y Zod Mini simultáneamente?

El código de tu biblioteca solo debe importar desde "zod/v4/core". Este subpaquete define las interfaces, clases y utilidades que se comparten entre Zod y Zod Mini.

// library code
import * as z4 from "zod/v4/core";
 
export function acceptObjectSchema<T extends z4.$ZodObject>(schema: T){
  // parse data
  z4.parse(schema, { /* somedata */});
  // inspect internals
  schema._zod.def.shape;
}

Al construir contra las interfaces base compartidas, puedes soportar de manera confiable ambos subpaquetes simultáneamente. Esta función puede aceptar tanto esquemas de Zod como de Zod Mini.

// user code
import { acceptObjectSchema } from "your-library";
 
// Zod 4
import * as z from "zod";
acceptObjectSchema(z.object({ name: z.string() }));
 
// Zod 4 Mini
import * as zm from "zod/mini";
acceptObjectSchema(zm.object({ name: zm.string() }))

Consulta la página de Zod Core para más información sobre los contenidos de la sub-biblioteca principal.

¿Cómo aceptar esquemas definidos por el usuario?

Aceptar esquemas definidos por el usuario es la operación fundamental para cualquier biblioteca construida sobre Zod. Esta sección describe las mejores prácticas para hacerlo.

Al comenzar, puede ser tentador escribir una función que acepte un esquema de Zod como este:

import * as z4 from "zod/v4/core";
 
function inferSchema<T>(schema: z4.$ZodType<T>) {
  return schema;
}

Este enfoque es incorrecto y limita la capacidad de TypeScript para inferir adecuadamente el argumento. No importa lo que pases, el tipo de schema será una instancia de $ZodType.

inferSchema(z.string());
// => $ZodType<string>

Este enfoque pierde información de tipo, a saber, qué subclase es realmente la entrada (en este caso, ZodString). Eso significa que no puedes llamar a ningún método específico de cadena como .min() en el resultado de inferSchema. En su lugar, tu parámetro genérico debe extender la interfaz del esquema principal de Zod:

function inferSchema<T extends z4.$ZodType>(schema: T) {
  return schema;
}
 
inferSchema(z.string());
// => ZodString ✅

Para restringir el esquema de entrada a una subclase específica:

 
import * as z4 from "zod/v4/core";
 
// solo acepta esquemas de objeto
function inferSchema<T>(schema: z4.$ZodObject) {
  return schema;
}

Para restringir el tipo de salida inferido del esquema de entrada:

 
import * as z4 from "zod/v4/core";
 
// solo acepta esquemas de cadena
function inferSchema<T extends z4.$ZodType<string>>(schema: T) {
  return schema;
}
 
inferSchema(z.string()); // ✅ 
 
inferSchema(z.number()); 
// ❌ The types of '_zod.output' are incompatible between these types. 
// // Type 'number' is not assignable to type 'string'

Para analizar datos con el esquema, usa las funciones de nivel superior z4.parse/z4.safeParse/z4.parseAsync/z4.safeParseAsync. La subclase z4.$ZodType no tiene métodos en ella. Los métodos de análisis habituales son implementados por Zod y Zod Mini, pero no están disponibles en Zod Core.

function parseData<T extends z4.$ZodType>(data: unknown, schema: T): z4.output<T> {
  return z.parse(schema, data);
}
 
parseData("sup", z.string());
// => string