eslint-plugin-zod

3.8.0 verified Sat Apr 25 auth: no javascript

An ESLint plugin providing custom lint rules to enforce best practices when using Zod (v3/v4). Current stable version 3.8.0, released Oct 2025, with minor releases every few weeks. Works with ESLint 9/10 and Oxlint 1.59+. Key differentiators: dedicated Zod linting, rules for schema consistency, import style, and error handling. Supports both zod and zod-mini. Ships TypeScript types.

Common errors

error Error: Cannot find module 'eslint-plugin-zod' ↓

cause Package not installed or incorrect import path.

fix

npm install eslint-plugin-zod --save-dev

error Configuration for rule "zod/require-schema-suffix" is invalid: Value {"suffix":"Schema","excludeFormattingUtils":true} should NOT have additional properties. ↓

cause The 'excludeFormattingUtils' option was added in v3.5.1; older versions throw error.

fix

Update eslint-plugin-zod to >=3.5.1 or remove the option.

error TypeError: Cannot read properties of undefined (reading 'configs') ↓

cause Importing configs as named export instead of default.

fix

Use import zodPlugin from 'eslint-plugin-zod' and then zodPlugin.configs.recommended.

error ESLint: Error: Failed to load plugin 'zod': Cannot find module 'zod' ↓

cause Missing peer dependency 'zod'.

fix

npm install zod

Warnings

breaking v3 requires ESLint 9+ (flat config). ESLint 8 is not supported. ↓

fix Migrate to ESLint 9 and use flat config format. See eslint-plugin-zod migration guide.

breaking v3 requires Node >=20. Older Node versions cause import errors. ↓

fix Upgrade Node to v20 or later.

deprecated Legacy rules like 'zod/prefer-enum' are removed and may cause lint errors if still referenced. ↓

fix Remove or replace deprecated rule names from config.

gotcha Plugin does not support ESLint's .eslintrc (JSON/JS) config format; only flat config. ↓

fix Use eslint.config.js with flat config.

gotcha Some rules (e.g., consistent-schema-output-type-style) are auto-fixable; review fixes as they may alter inferred types. ↓

fix Review changes before applying --fix; use suggestions for manual review.

Install

npm install eslint-plugin-zod

yarn add eslint-plugin-zod

pnpm add eslint-plugin-zod

Imports

plugin
wrong
```
const zodPlugin = require('eslint-plugin-zod')
```
correct
```
import zodPlugin from 'eslint-plugin-zod'
```
ESM-only since v3. Requires Node >=20. ESLint 9+ flat config expects default import.
rules
```
import { rules } from 'eslint-plugin-zod'
```
Named export for accessing rule definitions programmatically.

configs.recommended

wrong

import { configs } from 'eslint-plugin-zod'

correct

import zodPlugin from 'eslint-plugin-zod';
const config = [zodPlugin.configs.recommended];

Configs are nested under default export. Direct named import fails.

Quickstart

Flat config setup using the recommended config and custom rule configuration.

// eslint.config.js
import zodPlugin from 'eslint-plugin-zod';

export default [
  zodPlugin.configs.recommended,
  {
    rules: {
      'zod/require-schema-suffix': ['error', { suffix: 'Schema', excludeFormattingUtils: true }],
      'zod/prefer-string-schema-with-trim': 'error',
    },
  },
];