eslint-plugin-quality-gates

Structural quality gates for JavaScript/TypeScript repos: file naming, module contracts, layout conventions, and optional JSX attribute contracts.

This plugin does not replace style/safety rules from ESLint core, typescript-eslint, or unicorn. It enforces repo structure and export/attribute contracts.

Install

npm install --save-dev eslint-plugin-quality-gates

Requirements:

• ESLint ^8.57.0 || ^9.0.0
• Node.js ^18.18.0 || ^20.9.0 || >=21.1.0

Flat config (primary)

This package is ESM-only. Prefer ESLint flat config:

import qualityGates from 'eslint-plugin-quality-gates';

export default [
  qualityGates.configs.recommended,
  // or: qualityGates.configs.strict
];

Plugin key is quality-gates. Rule IDs look like quality-gates/file-naming-convention.

Manual flat setup

import qualityGates from 'eslint-plugin-quality-gates';

export default [
  {
    plugins: {
      'quality-gates': qualityGates,
    },
    rules: {
      'quality-gates/no-deep-relative-imports': ['error', { max: 1 }],
    },
  },
];

Legacy .eslintrc (limited)

Legacy shareable configs are exported as recommended-legacy / strict-legacy for ESM-aware tooling. Because this package is "type": "module" with no CJS build, extends: 'plugin:quality-gates/…' often fails under older require()-based ESLint 8 setups.

Prefer flat config, or merge rules manually:

import qualityGates from 'eslint-plugin-quality-gates';

export default [
  {
    plugins: { 'quality-gates': qualityGates },
    rules: qualityGates.configs['recommended-legacy'].rules,
  },
];

Presets

| Preset | Includes | |--------|----------| | recommended | file-naming-convention (PascalCase under src/components & src/pages, camelCase elsewhere; ignores tests/config/index), no-deep-relative-imports (max: 1), filename-match-export | | strict | recommended + no-default-export, require-sibling-file (**/components/**/*.{tsx,jsx} → {{name}}.test.tsx, ignores framework route files), folder-file-presence (src/features/* → index.ts) |

require-exports and require-attributes are not in presets — enable them with project-specific options.

Override strict starters for your tree when needed.

Rules

| Rule | Docs | Recommended | Strict | |------|------|-------------|--------| | file-naming-convention | Folder-scoped filename regexes | warn | warn | | require-exports | Require named exports | — | — | | require-attributes | Required HTML/JSX attributes | — | — | | filename-match-export | Basename matches primary export | error | error | | no-deep-relative-imports | Cap ../ depth | error | error | | no-default-export | Ban default exports | — | error | | require-sibling-file | Require colocated siblings | — | error | | folder-file-presence | Require files in folders | — | error |

Glob patterns

Ignore/file globs support *, **, ?, and brace lists (*.{ts,tsx}). They are not full micromatch (no extglobs like +(a|b), limited character classes). Prefer simple patterns. ! prefixes on ignore entries exclude paths from ignoring.

Folder options are resolved relative to ESLint’s cwd (falling back to process.cwd()).

Examples

• examples/basic — recommended gates (naming, export match, import depth)
• examples/strict — sibling tests, folder index.ts, no default export

npm run test:examples

Development

See CONTRIBUTING.md.

npm install
npm test
npm run lint
npm run build
npm run test:examples

Author

Zain (@zeddotes)

License

ISC