eslint-plugin-import-zod

1.2.1 verified Sat Apr 25 auth: no javascript

ESLint plugin (v1.2.1) that enforces namespace imports for zod (`import * as z from "zod"`) to improve tree-shaking and reduce bundle sizes. Targets eslint >=9 and Node >=20, ships TypeScript types. Auto-fixable: converts default/named imports to namespace imports, splits mixed imports. Released as v1.0.0 in 2025, with active development (recent patches). Unique vs other import rules: specifically for zod ecosystem.

Common errors

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

cause Package not installed or module resolution fails in CJS

fix

npm install -D eslint-plugin-import-zod and ensure ESLint is running in ESM mode.

error TypeError: importZod is not a function or config ↓

cause Using require() in CJS context

fix

Change to dynamic import: const importZod = (await import('eslint-plugin-import-zod')).default;

error Error: Failed to load plugin 'import-zod' declared in 'plugins': Cannot find module 'eslint-plugin-import-zod' ↓

cause ESLint cannot resolve plugin due to wrong config format

fix

Use flat config and import the plugin directly, not via string name.

Warnings

gotcha Plugin does not support CommonJS; must be used in ESM context. ↓

fix Use import syntax or configure ESLint as ESM.

gotcha The rule 'prefer-zod-namespace' auto-fixes imports by converting default imports to namespace imports; this may change module semantics. ↓

fix Review auto-fix changes; namespace import may affect type inference.

deprecated Deprecated pattern: import zod from 'zod' is auto-fixed to import * as zod from 'zod'. ↓

fix Use namespace import directly.

gotcha Plugin only works with ESLint flat config (eslint.config.js), not .eslintrc. ↓

fix Migrate to flat config or wrap plugin with compatibility layer.

Install

npm install eslint-plugin-import-zod

yarn add eslint-plugin-import-zod

pnpm add eslint-plugin-import-zod

Imports

importZod

wrong

const importZod = require('eslint-plugin-import-zod')

correct

import importZod from 'eslint-plugin-import-zod'

ESM-only; default export. Use dynamic import if needed in CJS.

prefer-zod-namespace

wrong

Use with require(): const importZod = require('eslint-plugin-import-zod')

correct

import importZod from 'eslint-plugin-import-zod'; ... rules: { 'import-zod/prefer-zod-namespace': 'error' }

Rule name is a string; imported plugin provides it.

configs.recommended

wrong

Using flat config array without spreading

correct

import importZod from 'eslint-plugin-import-zod'; export default [...importZod.configs.recommended]

configs.recommended is an array of config objects.

Quickstart

Sets up the plugin with recommended config and enables the prefer-zod-namespace rule in ESLint flat config.

import importZod from 'eslint-plugin-import-zod';

export default [
  ...importZod.configs.recommended,
  {
    rules: {
      'import-zod/prefer-zod-namespace': 'error',
    },
  },
];