Zod en el servidor y en el cliente: el schema que creés una vez y las tres formas en que se rompe en runtime

El 80% de los proyectos Next.js que usan Zod tienen el mismo schema importado desde tres contextos distintos. Y solo uno de esos tres contextos se comporta exactamente como Zod promete.

Sí, leíste bien. El modelo mental de "definí el schema una vez y validá en todos lados" es verdad en la librería, pero en un stack real con Next.js 16 —Server Actions, edge middleware y API routes— aparecen tres entornos de ejecución con restricciones distintas, y Zod no siempre llega completo a los tres.

Mi tesis es esta: Zod es una de las mejores herramientas del ecosistema TypeScript, pero compartir el mismo schema entre cliente, servidor Node.js y edge runtime sin pensar en las diferencias de contexto produce tres clases de falla específicas que no son obvias hasta que aparecen. Este post documenta esas tres fallas y el patrón que las evita.

El problema que nadie dibuja en el diagrama

Cuando empezás con Zod, el flujo parece limpio: un schema en lib/schemas/user.ts, lo importás desde el Server Action, desde el formulario del cliente y desde el middleware. TypeScript feliz, un solo source of truth.

El problema es que ese archivo .ts se ejecuta en tres motores diferentes según el contexto:

Zod en sí mismo es compatible con todos estos contextos en su core. El problema no es Zod: es lo que construís sobre Zod — refinements con lógica de Node.js, transforms que retornan tipos no serializables, y errores que viajan de vuelta al cliente sin filtro.

Falla #1: El .refine() que llama a Node.js sin avisar

El primer modo de falla aparece en el middleware. Tenés un schema de validación de sesión o de parámetros de ruta, lo ponés en middleware.ts, y en algún momento ese schema tiene un .refine() que adentro hace algo inocente como esto:

// lib/schemas/session.ts
import { z } from "zod"
import { isValidToken } from "@/lib/crypto" // ← usa Node.js crypto

export const sessionSchema = z.object({
  token: z.string().refine(
    async (val) => isValidToken(val), // ← llama a función con Node API
    { message: "Token inválido" }
  )
})

// middleware.ts — Edge Runtime
import { sessionSchema } from "@/lib/schemas/session"

export async function middleware(request: NextRequest) {
  const result = await sessionSchema.safeParseAsync({ token: getCookie(request) })
  // ← en Edge Runtime, esto puede fallar si isValidToken usa crypto.subtle de Node
}

El edge runtime de Next.js corre en un entorno V8 restringido —similar al de Cloudflare Workers— que no expone todas las APIs de Node.js. Si isValidToken internamente usa crypto de Node (no la Web Crypto API), el import explota en runtime, no en build time. TypeScript no lo va a atrapar porque la firma es válida.

La solución: los schemas que van al middleware tienen que ser edge-safe por diseño. Si necesitás lógica de validación que depende de Node.js APIs, esa lógica no va en el schema de edge — va en el Server Action que corre en Node.js.

// lib/schemas/edge/session.ts — solo validación estructural, sin lógica de Node
import { z } from "zod"

export const edgeSessionSchema = z.object({
  token: z.string().min(32).max(512), // validación estructural pura
  // Sin .refine() que llame a nada externo
})

// lib/schemas/server/session.ts — para Server Actions / API Routes en Node.js
import { z } from "zod"
import { isValidToken } from "@/lib/crypto"

export const serverSessionSchema = z.object({
  token: z.string().refine(
    async (val) => isValidToken(val),
    { message: "Token inválido" }
  )
})

Separar los schemas por capa de ejecución no es duplicar código: es documentar el contrato real de cada contexto. Podés leer más sobre cómo Web Crypto API difiere entre browser y Node.js en este análisis del stack — la misma lógica aplica a lo que podés poner en un .refine() de edge.

Falla #2: El .transform() que rompe la serialización en Server Actions

El segundo modo de falla es más sutil y aparece solo en Server Actions. Cuando un Server Action retorna datos, Next.js los serializa para enviarlos al cliente usando un protocolo basado en React Server Components (similar a JSON pero con soporte para Promises, Dates y algunos tipos especiales). La documentación oficial lo llama "serializable return values".

El problema: si tu schema usa .transform() para convertir datos en algo no serializable —un Map, una instancia de clase, un Set, o un objeto con métodos— y ese resultado viaja directo al cliente desde un Server Action, Next.js no puede serializarlo.

// lib/schemas/user.ts — schema compartido sin pensar en el contexto
import { z } from "zod"

export const userSchema = z.object({
  id: z.string(),
  roles: z.array(z.string()).transform(
    (roles) => new Set(roles) // ← Set no es serializable por React Server Components
  )
})

// app/actions/user.ts — Server Action
"use server"
import { userSchema } from "@/lib/schemas/user"

export async function getUser(formData: FormData) {
  const parsed = userSchema.parse({ id: formData.get("id"), roles: ["admin"] })
  return parsed // ← Next.js intenta serializar esto → error en runtime
}

TypeScript acepta este código. El build pasa. El error aparece en runtime cuando Next.js intenta serializar el Set para mandarlo al componente cliente.

La solución más directa: si el transform existe para comodidad interna del servidor, no lo pongas en el schema compartido. Poné el schema base (sin el transform) en el lugar compartido, y aplicá el transform solo dentro del Server Action o del service que lo necesita.

// lib/schemas/user.ts — schema base, sin transforms que rompan serialización
import { z } from "zod"

export const userSchema = z.object({
  id: z.string(),
  roles: z.array(z.string()) // array serializable
})

// Tipo inferido limpio para el cliente
export type User = z.infer<typeof userSchema>

// app/actions/user.ts
"use server"
import { userSchema } from "@/lib/schemas/user"

export async function getUser(formData: FormData) {
  const parsed = userSchema.parse({ id: formData.get("id"), roles: ["admin"] })
  // El transform al Set lo hacés acá, en el server, y no lo mandás al cliente
  const rolesSet = new Set(parsed.roles)
  return parsed // solo el objeto serializable
}

Esto conecta directamente con el modelo mental de caching en App Router: los datos que viajan entre server y client tienen restricciones que el código TypeScript no refleja. Si querés profundizar en esas restricciones desde el lado de React, el post sobre React 19 Server Components y caching cubre el modelo mental que falta en la documentación.

Falla #3: El error de Zod que llega al cliente sin sanitizar

La tercera falla es de seguridad y es la más fácil de introducir. Cuando zod.parse() falla, lanza un ZodError con un array de issues. Cada issue tiene path, message y code. Si capturas ese error en un Server Action y lo mandás directo al cliente sin procesarlo, le estás enviando la estructura interna de validación completa, incluyendo los nombres de los campos internos, los paths anidados y a veces mensajes que revelan lógica de negocio.

// ❌ Patrón inseguro — el ZodError completo viaja al cliente
"use server"
import { userSchema } from "@/lib/schemas/user"

export async function createUser(formData: FormData) {
  try {
    const data = userSchema.parse(Object.fromEntries(formData))
    // ...
  } catch (error) {
    // ← si es un ZodError, esto expone paths internos al cliente
    return { error: error instanceof Error ? error.message : "Error desconocido" }
  }
}

ZodError.message es un JSON serializado con todos los issues. En un campo de contraseña o en un campo que valida contra una lista interna de valores prohibidos, eso puede filtrar información.

El patrón correcto es usar safeParseAsync o safeParse y construir explícitamente el mensaje de error que querés que el cliente reciba:

// ✅ Patrón seguro — errores sanitizados
"use server"
import { userSchema } from "@/lib/schemas/user"

export async function createUser(formData: FormData) {
  const result = userSchema.safeParse(Object.fromEntries(formData))

  if (!result.success) {
    // Construís exactamente lo que querés exponer
    const publicErrors = result.error.issues.map((issue) => ({
      field: issue.path.join("."), // ¿querés exponer el path? decidís vos
      message: issue.message,      // ¿el mensaje es seguro para el cliente?
    }))
    return { success: false, errors: publicErrors }
  }

  // data está tipada correctamente
  const data = result.data
  // ...
  return { success: true }
}

Este patrón también hace más fácil internacionalizar los mensajes de error, porque tenés control explícito sobre lo que se manda.

Checklist de decisión: cómo compartir schemas entre contextos

Antes de importar un schema desde un nuevo contexto, pasalo por estas preguntas:

¿El schema va a correr en Edge Runtime (middleware)?
  → ¿Tiene .refine() o .transform() que llame a funciones externas?
    → SI: separá en un schema edge-safe con solo validación estructural
    → NO: podés reutilizarlo con cuidado

¿El schema va a ser retornado desde un Server Action al cliente?
  → ¿Tiene .transform() que produce Map, Set, Date compleja, instancia de clase?
    → SI: aplicá el transform en el servidor, retorná el tipo base serializable
    → NO: el schema base puede ser compartido

¿Los errores de validación van a llegar al cliente?
  → ¿Usás .parse() y catcheás el error directamente?
    → SI: reemplazá por .safeParse() y construí la respuesta de error manualmente
    → NO: revisá que los mensajes de error no expongan lógica interna

La regla de oro: el schema compartido solo debería tener validaciones estructurales puras —tipos, longitudes, formatos, obligatoriedad. Las validaciones que dependen de lógica de negocio, acceso a base de datos o APIs de Node.js van en schemas de server exclusivos.

Límites: qué no se puede concluir sin más evidencia

Este análisis está basado en la documentación oficial de Zod y Next.js, y en patrones reproducibles. Lo que no podés asumir a partir de esto:

• Que estos tres modos de falla son los únicos. En un stack con tRPC, Remix, o Edge Functions de Vercel las restricciones pueden diferir.
• Que el edge runtime de Next.js 16 y el de Vercel son idénticos en todos los casos. La documentación de Next.js y la de Vercel Edge Runtime tienen algunos matices propios.
• Que .transform() siempre rompe la serialización en Server Actions. Transforms que producen tipos primitivos, arrays de primitivos o plain objects funcionan. El problema es específico de tipos no-serializables por el protocolo de React Server Components.

Si querés verificar el comportamiento en tu propio stack, el experimento reproducible es simple: creá un schema con un .transform() que retorne un new Set(), usalo en un Server Action, e inspeccioná el error en la consola del navegador. El mensaje de Next.js es bastante claro sobre qué no puede serializar.

FAQ sobre Zod en producción con Next.js 16

¿Puedo usar el mismo schema de Zod en el cliente y en el servidor?
Sí, si el schema tiene solo validaciones estructurales puras (tipos, formatos, longitudes). El problema aparece cuando agregás .refine() con lógica que depende de APIs de Node.js o .transform() que produce tipos no serializables.

¿Zod funciona en el Edge Runtime de Next.js?
El core de Zod sí. Los problemas aparecen cuando los .refine() o .transform() dentro del schema llaman a código que usa APIs exclusivas de Node.js (como crypto, fs o buffer). Zod en sí mismo no usa esas APIs en su core.

¿Cuál es la diferencia entre parse() y safeParse() para Server Actions?
parse() lanza un ZodError en caso de falla, que hay que capturar con try/catch. safeParse() retorna { success: true, data } o { success: false, error } sin lanzar una excepción. Para Server Actions, safeParse() te da control explícito sobre qué errores mandás al cliente, que es la forma segura de manejarlo.

¿Puedo poner validaciones de base de datos dentro de un .refine() de Zod?
Podés, pero solo en schemas de server (nunca en schemas que corran en edge o cliente). Un .refine() async que consulta la base de datos para verificar unicidad de email es un patrón válido en un Server Action en Node.js. En edge runtime o en el cliente, eso no tiene sentido ni es posible.

¿Cómo sabés si un transform va a romper la serialización en un Server Action?
La regla práctica: si el tipo resultante del transform es Map, Set, una instancia de clase con métodos, o cualquier cosa que no sea serializable a JSON puro, no lo retornés directo desde el Server Action. Podés verificarlo en la documentación oficial de Next.js sobre serialización en Server Actions.

¿Vale la pena tener schemas separados por contexto si complica el proyecto?
La separación solo es necesaria donde hay diferencias reales: si no tenés middleware con lógica de validación, no necesitás schemas de edge. La regla mínima es: un schema base compartido con validaciones estructurales, y schemas extendidos con .refine() / .transform() solo donde el contexto lo permite.

Postura final y próximo paso

Zod no está roto. El modelo de "definí una vez" funciona perfectamente para validaciones estructurales puras que no dependen del entorno de ejecución. El problema es que en Next.js 16 con Server Actions y middleware, ese entorno de ejecución cambia de forma silenciosa y TypeScript no te avisa.

Lo que sí compro: Zod como fuente de verdad de los tipos y la estructura de los datos. Lo que no compro sin pensar: usar el mismo schema con transforms y refinements complejos en los tres contextos sin separar responsabilidades.

El patrón que funciona es simple: schema base compartido con validaciones estructurales, schemas de server para lógica con Node.js, y safeParse() siempre que los errores puedan viajar al cliente. No es overhead —es documentar explícitamente qué contrato pertenece a qué capa.

El próximo paso concreto: si tenés un proyecto con Zod en Next.js 16, buscá todos los lugares donde importás un schema que tiene .refine() o .transform(), y verificá en qué contexto corre. Tres minutos de grep pueden ahorrarte un error de runtime que solo aparece en producción.

Fuente original:

• Zod Documentation: https://zod.dev/
• Next.js Server Actions Docs: https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations

Este artículo fue publicado originalmente en juanchi.dev