Versionado

Actualización — 8 de Julio de 2025

[email protected] ha sido publicado en npm. La raíz del paquete ("zod") ahora exporta Zod 4. Todas las demás subrutas no han cambiado y permanecerán disponibles para siempre.

Para actualizar a Zod 4:

npm install zod@^4.0.0

Si estás utilizando Zod 4, tus importaciones actuales ("zod/v4" y "zod/v4-mini") seguirán funcionando para siempre. Sin embargo, después de actualizar, opcionalmente puedes reescribir tus importaciones de la siguiente manera:

Autores de bibliotecas — si ya has implementado el soporte para Zod 4 de acuerdo con las mejores prácticas descritas en la guía para Autores de bibliotecas, actualiza tu dependencia par (peer dependency) para incluir zod@^4.0.0:

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

No debería haber otros cambios de código necesarios. No se realizaron cambios de código entre la última versión 3.25.x y la 4.0.0. Esto no requiere un cambio de versión mayor.

Versionado en Zod 4

Este es un informe del enfoque de Zod 4 para el versionado, con el objetivo de facilitar la migración a Zod 4 para los usuarios y el ecosistema de bibliotecas asociadas de Zod.

El enfoque general:

• Zod 4 no se publicará inicialmente como [email protected] en npm. En su lugar, se exportará en una subruta ("zod/v4") junto a [email protected]
• A pesar de esto, Zod 4 se considera estable y listo para producción.
• Zod 3 continuará exportándose desde la raíz del paquete ("zod") así como desde una nueva subruta "zod/v3". Continuará recibiendo correcciones de errores y mejoras de estabilidad.

Algún tiempo después:

• La raíz del paquete ("zod") cambiará de exportar Zod 3 a Zod 4
• En este punto [email protected] se publicará en npm
• La subruta "zod/v4" permanecerá disponible para siempre

¿Por qué?

Zod ocupa un lugar único en el ecosistema. Muchas bibliotecas/marcos de trabajo en el ecosistema aceptan esquemas Zod definidos por el usuario. Esto significa que su API orientada al usuario está fuertemente acoplada a Zod y sus diversas clases/interfaces/utilidades. Para estas bibliotecas/marcos de trabajo, un cambio disruptivo en Zod causa necesariamente un cambio disruptivo para sus usuarios. Un ZodType de Zod 3 no es asignable a un ZodType de Zod 4.

¿Por qué las bibliotecas no pueden simplemente soportar v3 y v4 simultáneamente?

Desafortunadamente, las limitaciones de peerDependencies (e inconsistencias entre los gestores de paquetes) hacen extremadamente difícil soportar elegantemente dos versiones mayores de una biblioteca simultáneamente.

Si publicara ingenuamente [email protected] en npm, la gran mayoría de las bibliotecas en el ecosistema de Zod necesitarían publicar una nueva versión mayor para soportar adecuadamente Zod 4, incluidas algunas bibliotecas de alto perfil como el AI SDK. Desencadenaría una "avalancha de cambios de versión" en todo el ecosistema y generalmente crearía una gran cantidad de frustración y trabajo.

Con el versionado de subrutas, resolvemos este problema. Proporciona una forma sencilla para que las bibliotecas soporten Zod 3 y Zod 4 (incluido Zod Mini) simultáneamente. Pueden continuar definiendo una única peerDependency en "zod"; no hay necesidad de soluciones más arcanas como alias de npm, dependencias pares opcionales, un paquete "zod-compat", u otros trucos similares.

Las bibliotecas necesitarán aumentar la versión mínima de su dependencia par "zod" a zod@^3.25.0. Luego pueden hacer referencia tanto a Zod 3 como a Zod 4 en su implementación:

import * as z3 from "zod/v3"
import * as z4 from "zod/v4"

Más tarde, una vez que haya un amplio soporte para v4, aumentaremos la versión mayor en npm y comenzaremos a exportar Zod 4 desde la raíz del paquete, completando la transición. (Esto ya ha sucedido; ver la nota en la parte superior de esta página.)

Mientras las bibliotecas importen exclusivamente de las subrutas asociadas (no de la raíz), sus implementaciones seguirán funcionando a través del cambio de versión mayor sin cambios de código.

Si bien puede parecer poco ortodoxo (¡al menos para las personas que no usan Go!), este es el único enfoque que conozco que permite una ruta de migración limpia e incremental tanto para los usuarios de Zod como para las bibliotecas en el ecosistema más amplio.

Una inmersión más profunda en por qué las dependencias pares no funcionan en esta situación.

Imagina que eres una biblioteca tratando de construir una función acceptSchema que acepta un esquema Zod. Quieres poder aceptar esquemas de Zod 3 o Zod 4. En este hipotético, imagino que Zod 4 se publicó como zod@4 en npm, sin subrutas. Aquí están tus opciones:

1. Instalar tanto zod@3 como zod@4 como dependencies simultáneamente usando alias de npm. Esto funciona pero terminas incluyendo tus propias copias de Zod 3 y Zod 4. No tienes garantía de que los esquemas Zod de tu usuario sean instancias de la misma clase z.ZodType que estás extrayendo de las dependencias (las comprobaciones instanceof probablemente fallarán).

2. Usar una dependencia par que abarque múltiples versiones mayores: "zod@>=3.0.0" …pero al desarrollar una biblioteca todavía necesitarías elegir una versión contra la cual desarrollar. Usualmente instalarías esto como una dependencia de desarrollo. La responsabilidad recae en ti para asegurar minuciosamente que tu código funcione, carácter por carácter, en ambas versiones. Esto es imposible en el caso de Zod 3 y Zod 4 porque una serie de clases muy fundamentales han simplificado/cambiado sus genéricos.

3. Dependencias pares opcionales. Simplemente no pude encontrar una respuesta directa sobre cómo determinar de manera confiable qué dependencia par está instalada en tiempo de ejecución en todas las plataformas. Muchas respuestas en línea dirán "usa importaciones dinámicas en un try/catch para verificar si un paquete existe". Esas personas asumen que estás en el backend porque los empaquetadores de frontend no tienen capacidad para esto. Fallarán cuando intentes empaquetar una dependencia que no está instalada. Obviamente no importa si estás dentro de un try/catch durante un paso de compilación. Además: dado que estamos hablando de múltiples versiones de la misma biblioteca, necesitarías usar alias de npm para diferenciar las dos versiones en tu package.json. Versiones de npm tan recientes como v10 no pueden manejar la combinación de dependencias pares + alias de npm.

4. zod-compat. Esta solución extremadamente vaga que ves en línea es "definir interfaces para cada versión que representen alguna funcionalidad básica". Básicamente algunos tipos de utilidad que las bibliotecas pueden usar para aproximar lo real. Esto es propenso a errores, una tonelada de trabajo, necesita mantenerse sincronizado con las implementaciones reales, y en última instancia las bibliotecas están desarrollando contra una versión sombra de tu biblioteca que probablemente carece de detalles. También solo funciona para tipos: si una biblioteca depende de cualquier código en tiempo de ejecución en Zod, se desmorona.

Por lo tanto, subrutas.