Installation

This guide will walk you through installing zod-validation-error and verifying your environment meets the necessary prerequisites.

Package Manager

Install the package using your preferred Node.js package manager.

With npm: 

npm install zod-validation-error

With Yarn: 

yarn add zod-validation-error

With pnpm: 

pnpm add zod-validation-error

With Bun: 

bun add zod-validation-error

Prerequisites

Before using this library in production, ensure your environment meets the following minimum requirements:

  • Node.js: v18.0.0 or higher. (The library utilizes modern JavaScript features available in Node 18+).
  • TypeScript: v4.5 or higher. (Required if you are compiling TypeScript; earlier versions may struggle with some advanced generic types used in Zod).

Peer Dependencies

zod-validation-error is designed to augment Zod, meaning zod itself must be installed in your project. The library acts as a peer dependency consumer.

We officially support both the older v3 and the newer v4 releases of Zod:

{
  "peerDependencies": {
    "zod": "^3.25.0 || ^4.0.0"
  }
}

If you do not have Zod installed, you must install it alongside this library:

npm install zod zod-validation-error

Module Resolution (ESM vs CommonJS)

The package is bundled to support both ECMAScript Modules (ESM) and CommonJS (CJS) seamlessly. Depending on your project's tsconfig.json or package.json ("type": "module"), you can import the library in two ways:

import { fromError, createErrorMap } from 'zod-validation-error';

CommonJS Require

const { fromError, createErrorMap } = require('zod-validation-error');

Zod v3 vs Zod v4 Exports

Because Zod introduced significant architectural changes between version 3 and version 4, zod-validation-error provides compartmentalized exports.

  • Default Exports (Zod v4): If you use import { ... } from 'zod-validation-error', you are importing the Zod v4 compatible logic.
  • Zod v3 Exports: If you are still using Zod v3 in your project, you must explicitly import from the /v3 path. See the Zod v3 Support page for detailed migration and usage instructions.

Troubleshooting Installation

Peer Dependency Warnings

If your package manager throws a warning about an unmet peer dependency for zod, verify which version of Zod you have installed. Ensure it is at least 3.25.0.

If you have multiple dependencies relying on different versions of Zod, you may encounter instanceof prototype chain issues. In this case, ensure you rely on this library's heuristic type guards (like isZodErrorLike) rather than native instanceof checks. (See Type Guards).