Registry / devops / eslint-plugin-zod-openapi

eslint-plugin-zod-openapi

library2.0.0jsnpmunverified

ESLint plugin providing custom lint rules for projects using zod-openapi, which extends Zod with OpenAPI metadata. Version 2.0.0 requires Node >=16.11 and ships TypeScript types. It enforces best practices like requiring `.meta()`, JSDoc comments, and examples on Zod types, and provides auto-fixable rules. Differentiates from generic ESLint plugins by being purpose-built for zod-openapi's `.meta()` chain pattern. Released via GitHub Releases with manual tagging.

devops

npm install eslint-plugin-zod-openapi

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ESLINT-PLUGIN-ZOD-

eslint-plugin-zod-openapi

devopsjavascriptv2.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ module.exports = { plugins: ['zod-openapi'] }

✗ const zodOpenapiEslint = require('eslint-plugin-zod-openapi')

The plugin should be referenced by name 'zod-openapi' in the plugins array, not required directly. Configuration is done via rules object.

require-meta

✓ rules: { 'zod-openapi/require-meta': 'error' }

✗ rules: { 'require-meta': 'error' }

Rule names are prefixed with 'zod-openapi/' in the rules object. Forgetting the prefix will not apply the rule.

require-comment

✓ rules: { 'zod-openapi/require-comment': 'error' }

✗ rules: { 'zod-openapi/require-comment': ['error', { /* options */ }] }

Rule does not accept options. The fix is auto-applied with --fix.

prefer-zod-default

✓ rules: { 'zod-openapi/prefer-zod-default': 'warn' }

✗ rules: { 'zod-openapi/prefer-zod-default': 'error' }

Typical usage is as warn; severity can be adjusted per project.

ESLint configuration enabling all zod-openapi rules with overrides for API type files.

// .eslintrc.js module.exports = { plugins: ['zod-openapi'], rules: { 'zod-openapi/require-meta': 'error', 'zod-openapi/require-comment': 'error', 'zod-openapi/require-example': 'warn', 'zod-openapi/prefer-meta-last': 'warn', 'zod-openapi/prefer-zod-default': 'warn', }, overrides: [ { files: ['src/api-types/*.ts'], rules: { 'zod-openapi/require-meta': 'error', }, }, ], };

Debug

Known issues

gotchaRule names must be prefixed with 'zod-openapi/' in the rules object, e.g., 'zod-openapi/require-meta'. Omitting the prefix will silently fail to apply the rule.

fix

Ensure rule keys in ESLint config are prefixed with 'zod-openapi/'.

affects: >=1.0.0

gotchaThe plugin expects all Zod objects to use zod-openapi's `.meta()` method. If used with plain Zod objects without `.meta()`, the 'require-meta' rule will flag errors unless you scope it via overrides.

fix

Use ESLint overrides to apply rules only to files that use zod-openapi, or ensure all Zod objects have `.meta()`.

affects: >=1.0.0

breakingVersion 2.0.0 drops support for Node <16.11. Projects on older Node versions will see install/run failures.

fix

Upgrade Node to >=16.11.

affects: >=2.0.0

deprecatedThe 'require-comment' rule auto-fixes missing descriptions but may need JSDoc comment style adjustments; it is generally safe but could conflict with other comment rules.

fix

Review auto-fix output manually if using other ESLint plugins that impose comment formatting.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Failed to load plugin 'zod-openapi' declared in '.eslintrc.js': Cannot find module 'eslint-plugin-zod-openapi'

Plugin not installed in the project's node_modules.

fix

Install the plugin: npm i -D eslint-plugin-zod-openapi

Definition for rule 'zod-openapi/require-meta' was not found.

ESLint encountered the rule name before loading the plugin correctly, typically due to missing plugin in 'plugins' array.

fix

Add 'zod-openapi' to the 'plugins' array in your ESLint config.

TypeError: Cannot read properties of undefined (reading 'meta')

The rule expects a Zod object with a .meta() method, but encountered a Zod schema that does not have it (e.g., plain Zod usage).

fix

Ensure the file uses zod-openapi's z.object(...).meta(...) or exclude the file from the rule via overrides.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

eslintoptionalPeer dependency required to use the plugin as an ESLint rule set.

Agent activity

7 hits · last 30 days

node

Bingbot

Resources

githubssh://git@github.com/samchungy/eslint-plugin-zod-openapi ↗

packageeslint-plugin-zod-openapi ↗

homepagehttps://github.com/samchungy/eslint-plugin-zod-openapi#readme ↗