eslint-plugin-zod-x

ESLint plugin that adds custom linting rules to enforce best practices when using Zod

Rules

💼 Configurations enabled in.
✅ Set in the recommended configuration.
🔧 Automatically fixable by the --fix CLI option.
💡 Manually fixable by editor suggestions.

| Name                             | Description | 💼 | 🔧 | 💡 | | :--------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------- | :-- | :-- | :-- | | array-style | Enforce consistent Zod array style | ✅ | 🔧 | | | consistent-import-source | Enforce consistent source from Zod imports | | | 💡 | | consistent-object-schema-type | Enforce consistent usage of Zod schema methods | | | 💡 | | no-any | Disallow usage of z.any() in Zod schemas | ✅ | | 💡 | | no-empty-custom-schema | Disallow usage of z.custom() without arguments | ✅ | | | | no-number-schema-with-int | Disallow usage of z.number().int() as it is considered legacy | ✅ | 🔧 | | | no-optional-and-default-together | Disallow using both .optional() and .default() on the same Zod schema | ✅ | 🔧 | | | no-throw-in-refine | Disallow throwing errors directly inside Zod refine callbacks | ✅ | | | | no-unknown-schema | Disallow usage of z.unknown() in Zod schemas | | | | | prefer-meta | Enforce usage of .meta() over .describe() | ✅ | 🔧 | | | prefer-meta-last | Enforce .meta() as last method | ✅ | 🔧 | | | prefer-namespace-import | Enforce importing zod as a namespace import (import * as z from 'zod') | ✅ | 🔧 | | | prefer-strict-object | Enforce usage of .strictObject() over .object() and/or .looseObject() | | | | | require-brand-type-parameter | Require type parameter on .brand() functions | ✅ | | 💡 | | require-error-message | Enforce that custom refinements include an error message | ✅ | 🔧 | | | require-schema-suffix | Require schema suffix when declaring a Zod schema | ✅ | | | | schema-error-property-style | Enforce consistent style for error messages in Zod schema validation (using ESQuery patterns) | | | |

Installation

Install eslint and eslint-plugin-zod-x using your preferred package manager:

npm i --save-dev eslint eslint-plugin-zod-x

yarn add --dev eslint eslint-plugin-zod-x

pnpm add --save-dev eslint eslint-plugin-zod-x

Configuration

1. Import the plugin

   import eslintPluginZodX from 'eslint-plugin-zod-x';

2. Add recommended config to your ESLint setup

   eslintPluginZodX.configs.recommended,

Here’s a minimal example using the flat config format:

// eslint.config.js
import { defineConfig } from 'eslint/config';
import eslint from '@eslint/js';
import eslintPluginZodX from 'eslint-plugin-zod-x';

export default defineConfig(
  eslint.configs.recommended,
  eslintPluginZodX.configs.recommended,
);

Zod peer dependency version

eslint-plugin-zod-x is designed for projects that use zod@^4. While the plugin analyzes Zod schemas in your code, it doesn’t import or depend on Zod at runtime. To document this relationship without forcing installation, Zod is declared as an optional peer dependency in the plugin’s package.json.

If your project uses Zod v4, the plugin will automatically lint your schemas. If you’re not using Zod (for example, in a separate ESLint workspace), you don’t need to install it.