eslint-plugin-zod-mini

ESLint plugin that adds custom linting rules to enforce best practices when using Zod Mini (zod/mini).

It can also work with Oxlint!
Find out more about Oxlint's jsPlugins.

Rules

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

| Name                                | Description | 💼 | 🔧 | 💡 | | :--------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- | :-- | :-- | :-- | | consistent-import | Enforce a consistent import style for Zod Mini | ✅ | 🔧 | | | consistent-import-source | Enforce consistent source from Zod Mini imports | | | 💡 | | consistent-object-schema-type | Enforce consistent usage of Zod Mini schema methods | | | 💡 | | consistent-schema-output-type-style | Enforce consistent use of z.infer or z.output for schema type inference | | 🔧 | | | consistent-schema-var-name | Enforce a consistent naming convention for Zod Mini schema variables | ✅ | | | | no-any-schema | Disallow usage of z.any() in Zod Mini schemas | ✅ | | 💡 | | no-coerce-boolean | Disallow z.coerce.boolean() because it treats any non-empty string as true. | ✅ | | 💡 | | no-conflicting-checks | Disallow check combinations that can never match, are redundant, or do not apply to the schema type | | | | | no-duplicate-schema-methods | Disallow calling the same schema method more than once in a single chain | ✅ | | | | no-dynamic-schema-value | Disallow non-static values passed as arguments in a Zod Mini schema expression | | | | | no-empty-custom-schema | Disallow usage of z.custom() without arguments | ✅ | | | | no-function-scoped-schema | Disallow constructing a Zod Mini schema inside a function body | | | | | no-native-enum | Disallow deprecated z.nativeEnum() in favor of z.enum(). | ✅ | 🔧 | | | no-promise-schema | Disallow deprecated z.promise() schemas. | ✅ | | | | no-throw-in-refine | Disallow throwing errors directly inside Zod Mini refine callbacks | ✅ | | | | no-transform-in-record-key | Disallow transforms in z.record() key schemas, which can cause silent key mutations and data loss through key collisions | | | | | no-unknown-schema | Disallow usage of z.unknown() in Zod Mini schemas | | | | | no-unnecessary-readonly | Disallow z.readonly() on schemas whose output is already immutable | | 🔧 | | | prefer-enum-over-literal-union | Prefer z.enum() over z.union() when all members are string literals. | ✅ | 🔧 | | | prefer-map-set-size-over-min-max | Prefer z.size(n) over z.minSize(n) and z.maxSize(n) with the same value on a set or map schema | | 🔧 | | | prefer-meta | Enforce usage of z.meta() over z.describe() | ✅ | 🔧 | | | prefer-nullish | Enforce z.nullish() instead of combining z.optional() and z.nullable() | ✅ | 🔧 | | | prefer-string-length-over-min-max | Prefer z.length(n) over z.minLength(n) and z.maxLength(n) with the same value on a string schema | | 🔧 | | | prefer-tuple-over-array-length | Prefer z.tuple() over a length-constrained z.array() so the length is preserved in the inferred type. | | 🔧 | | | prefer-validate | Prefer boolean validation when only the success of parsing is used | | | 💡 | | require-brand-type-parameter | Require type parameter on .brand() functions | ✅ | | 💡 | | require-error-message | Enforce that custom refinements include an error message | ✅ | 🔧 | | | schema-error-property-style | Enforce consistent style for error messages in Zod Mini schema validation (using ESQuery patterns) | | | |

Installation

ESLint

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

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

yarn add --dev eslint eslint-plugin-zod-mini

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

ESLint Configuration

1. Import the plugin

   import eslintPluginZodMini from 'eslint-plugin-zod-mini';

2. Add recommended config to your ESLint setup

   eslintPluginZodMini.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 eslintPluginZodMini from 'eslint-plugin-zod-mini';

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

Oxlint

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

npm i --save-dev oxlint eslint-plugin-zod-mini

yarn add --dev oxlint eslint-plugin-zod-mini

pnpm add --save-dev oxlint eslint-plugin-zod-mini

Oxlint Configuration

1. Import the plugin

   import eslintPluginZodMini from 'eslint-plugin-zod-mini';

2. Add eslint-plugin-zod-mini to the jsPlugins key

   {
     jsPlugins: ['eslint-plugin-zod-mini'],
     // ...
   }

3. Add eslintPluginZodMini.configs.recommended.rules to your Oxlint config.
   Alternatively you can specify the rules manually

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

// oxlint.config.ts
import eslintPluginZodMini from 'eslint-plugin-zod-mini';
import { defineConfig } from 'oxlint';

export default defineConfig({
  jsPlugins: ['eslint-plugin-zod-mini'],
  rules: {
    ...eslintPluginZodMini.configs.recommended.rules,
  },
});

Zod peer dependency version

eslint-plugin-zod-mini is designed for projects that use zod@^4 (specifically zod/mini). While the plugin analyzes Zod Mini 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 Mini, 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.