@exadev/eslint-config
v3.1.0
Published
Shared custom ESLint rules and plugin for ExaDev projects
Maintainers
Readme
@exadev/eslint-config
A real ESLint plugin (not a shareable config) exposing custom rules shared across ExaDev projects. Also published under the unscoped alias
exadev-eslint-config.
Contents: Why · Getting started · The lighter option · Optional features · Rules · Barrel policy · Tool config files · Tooling wiring · Verifying ESLint is applied · Workspace architecture · Turbo · Development · License
Why
Multiple ExaDev repos carried identical copies of a handful of custom ESLint rules (barrel/index discipline, re-export placement, pointless-alias detection). This package is the single source of truth for those rules. Only the rules are centralized — not a consumer's whole eslint.config.ts, since file-scoping, tsconfig wiring, and runtime-isomorphism import bans are genuinely project-specific. Each consumer keeps its own eslint.config.ts, importing rule implementations from here.
Getting started
pnpm add -D @exadev/eslint-config typescript-eslint eslintRequires eslint >=10.0.0 and typescript-eslint >=8.0.0 as peer dependencies. Importing anything from this package resolves typescript-eslint, since the default export and the plugin named export share one root module — see Architecture.
// eslint.config.ts
import { defineConfig } from 'eslint/config';
import exadev from '@exadev/eslint-config';
export default defineConfig(
{
languageOptions: {
parserOptions: { project: './tsconfig.json', tsconfigRootDir: import.meta.dirname },
},
},
...exadev,
// ...your own config on top...
);Why defineConfig() rather than tseslint.config() here: tseslint.config() is now @deprecated upstream in favour of ESLint core's own defineConfig(), so this package's default export is typed against ESLint core's own config type specifically so it satisfies defineConfig() directly. If you haven't migrated off tseslint.config() yet, it still works exactly the same — this package's exported config array is typed to satisfy either wrapper, and that compatibility is itself covered by a real regression test (src/consumer-compatibility.ts) — but new consumers should reach for defineConfig().
Remove your own tseslint.configs.recommended/recommendedTypeChecked/strictTypeChecked/stylisticTypeChecked spreads. The default export already includes strictTypeChecked (which subsumes both plain recommended and recommendedTypeChecked) plus stylisticTypeChecked, and registers the @typescript-eslint plugin/parser itself — flat config rejects two different plugin object instances registered under the same namespace. You still supply your own languageOptions.parserOptions.project/projectService pointing at your tsconfig(s).
Remove your own plugins: { '@stylistic': ... } registration too. The default export bundles @stylistic/eslint-plugin (see Stylistic comment, class-member and JSX rules) and registers it under the @stylistic namespace itself, so a consumer block registering its own copy of the plugin (a different version resolved from elsewhere in the lockfile, or a duplicated install) makes ESLint throw Config: Key "plugins": Cannot redefine plugin "@stylistic". at config load, the identical flat-config restriction as the typescript-eslint case above. Registering the very same instance is harmless, but the robust migration is to drop the registration entirely: configure any further @stylistic/* rules directly in your own rules block, since this package's block already registers the plugin for every JS/TS and JSX file.
Your own blocks need no plugins: { exadev } and no files. exadevConfig() registers the exadev plugin for every file it lints, so a block placed after it that sets an exadev/* rule written for JavaScript and TypeScript, such as { rules: { 'exadev/barrel-policy': ['error', { mode: 'siblings' }] } }, loads even though it also applies to tsconfig.json, other JSON files and Markdown, and a rule that inspects JavaScript or TypeScript syntax leaves those files alone. The JSON and Markdown rules (package-json-key-order, markdown-required-heading, the workspace architecture and Turbo rules) are the exception: ESLint refuses to enable a rule for a language it does not declare, so a block that sets one needs the files of the kind of file it reads, which its preset already supplies.
Rules from other plugins are different. @typescript-eslint/*, @stylistic/*, jsdoc/*, unicorn/* and the rest are registered only for JavaScript and TypeScript files, so a block of your own that sets one needs files: ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}']; without it ESLint fails at config load with could not find plugin as soon as the block also applies to a JSON or Markdown file.
What the default export includes
typescript-eslint presets:
strictTypeChecked+stylisticTypeChecked— already coversno-deprecated,no-misused-spread,no-mixed-enums,no-unnecessary-condition,use-unknown-in-catch-callback-variable,return-await,related-getter-setter-pairs,no-unnecessary-type-parameters, and more (not re-listed individually below).
This package's own rules (full details in Rules):
exadev/barrel-policyat its auto-detecting default — see Barrel policyexadev/no-object-assignexadev/no-mutable-union-array-paramexadev/no-array-isarray-mutationexadev/no-enum-number-wideningexadev/no-enum-reverse-lookup-wideningexadev/no-map-instanceof-mutationexadev/no-set-instanceof-mutationexadev/prefer-readonly-array-paramexadev/prefer-readonly-object-paramexadev/prefer-numeric-sort-compareexadev/prefer-options-object-paramexadev/multiline-comment-styleexadev/prefer-doc-commentexadev/no-pointless-reassignmentexadev/test-file-kind
Individual rule tuning, each with its own reasoning:
linterOptions.noInlineConfig— noeslint-disablecomments of any kind.consistent-type-assertions— bans all type assertions (relaxed in test files, see below).consistent-type-importsandconsistent-type-exports— plain presence, no extra config.consistent-return— a function can't implicitly returnundefinedon one path and a real value on another.- Why: that split is usually a bug, not a deliberate design.
no-non-null-assertion— bans the!operator.- Why: it's the same manual-override escape hatch as a type assertion, under a different spelling.
no-redeclareandno-shadow— plain presence, no extra config.no-use-before-defineset to{ functions: false }— everything except function declarations must be defined before use.- Why:
let/const/class/enum bindings have a genuine temporal-dead-zone crash risk, but function declarations are fully hoisted and safe to call before their point of textual declaration — this codebase's own rule files consistently define helper functions after the logic that calls them.
- Why:
ban-ts-comment— bans@ts-expect-erroroutright (relaxed in test files, see below).method-signature-styleset to'property'.- Why: method-shorthand signatures are checked bivariantly under
strictFunctionTypes, which is unsound.
- Why: method-shorthand signatures are checked bivariantly under
prefer-readonly,promise-function-async,require-array-sort-compare— plain presence, no extra config.strict-void-return— bans passing a value-returning function where a void-returning one is expected (e.g.arr.forEach(x => otherArray.push(x))).- Why: not yet in any typescript-eslint preset; this typechecks today only because of TS's own void-return contravariance leniency.
strict-boolean-expressionsat the rule's own bare defaults.- Why: an unambiguous non-nullable truthy check stays allowed; an ambiguous nullable check does not.
no-magic-numbers— tuned to exempt array indexes, enum members, readonly class properties, default parameter values, numeric literal types (e.g.type Indent = 2 | 4), and the handful of universally-idiomatic bare numbers (-1,0,1,2).max-linesset to{ max: 800, skipBlankLines: true, skipComments: true }.- Why: counting only real code means a file isn't pushed over the limit by whitespace or its own WHY-explanation comments.
max-paramsset to{ max: 4 }, one above the rule's own default of3. Needs no type information — registered in bothplugin.configs.recommendedand the default (type-checked) export, likeexadev/prefer-readonly-array-paramabove.- Why: a deliberately loose backstop against a genuinely excessive number of REQUIRED parameters, distinct from
exadev/prefer-options-object-paramabove, which already offers a real fix for the more common shape (a run of 2+ trailing OPTIONAL parameters) this rule structurally cannot see until the total count crosses its own threshold.
- Why: a deliberately loose backstop against a genuinely excessive number of REQUIRED parameters, distinct from
no-warning-comments— bans any comment containingStryker disable.- Why: that's Stryker's own mutation-testing suppression directive, invisible to
noInlineConfigabove since it isn't an eslint-disable comment.
- Why: that's Stryker's own mutation-testing suppression directive, invisible to
explicit-module-boundary-types: an exported function or class member writes out its parameter and return types. TypeScript files only (.ts,.tsx,.mts,.cts): the rule reads annotations from the syntax, never from JSDoc, so it could not be satisfied in plain JavaScript typed through@type,@param {T}and@returns {T};tsc --checkJscovers those files.- Why: an inferred return type changes silently when the body does;
isolatedDeclarationsis the compiler-side alternative and is a tsconfig matter.
- Why: an inferred return type changes silently when the body does;
switch-exhaustiveness-checkset to{ considerDefaultExhaustiveForUnions: false, requireDefaultForNonUnion: true }.- Why: a
defaultbranch cannot stand in for handling a newly added union member, and a switch over a non-union needs adefaultbecause the checker cannot prove its cases complete.
- Why: a
- Core robustness rules:
eqeqeq,no-implicit-coercion,no-param-reassign,no-await-in-loop,require-atomic-updates,default-case-last,no-return-assignandmax-depth. See Robustness rules.
JSDoc and TSDoc (see src/jsdoc.ts): eslint-plugin-jsdoc's flat/recommended-tsdoc-error bundle checks an existing doc comment in every JavaScript and TypeScript file, with the requirements tier (whether a comment must exist) turned off, and eslint-plugin-tsdoc's tsdoc/syntax validates its TSDoc syntax. Two rules apply to TypeScript files only (.ts, .tsx, .mts, .cts): tsdoc/syntax and jsdoc/no-types, which together forbid a {type} in a doc comment because TypeScript already states the type. In plain JavaScript (.js, .jsx, .mjs, .cjs) a JSDoc annotation (@type {...}, @param {T}, @returns {T}) is the only place a type can be written, and tsc --checkJs reads it, so both rules stay off there and the rest of the jsdoc bundle (tag names, parameter names, type validity) still applies.
Test files (**/*.{test,spec}.{ts,tsx,mts,cts,js,jsx,mjs,cjs}) get two narrow relaxations of this package's own additions, and only these two:
@ts-expect-errorreverts toallow-with-description.- Why: a compile-time-only assertion of a type failure is a legitimate test pattern;
@ts-ignore/@ts-nocheckstay banned since@ts-expect-erroris strictly better.
- Why: a compile-time-only assertion of a type failure is a legitimate test pattern;
consistent-type-assertionsrelaxes toassertionStyle: 'as'.- Why: the legacy
<Type>valueform stays banned everywhere.
- Why: the legacy
Nothing else inherited from the presets is relaxed.
Robustness rules
Core ESLint rules that nothing in the typescript-eslint presets enables. All need no type information, so plugin.configs.recommended carries them as well, with the same settings except no-implicit-coercion (below).
| Rule | Setting | Why |
| --- | --- | --- |
| eqeqeq | always | == null hides which of null and undefined the code means, so there is no null carve-out. |
| no-implicit-coercion | { boolean: false } in the default export, defaults in plugin.configs.recommended | !!value is allowed where strict-boolean-expressions backs it, because that rule already rejects ! on an operand whose truthiness is ambiguous (a nullable string or number). plugin.configs.recommended registers no typescript-eslint rules, so it keeps banning !!. +value, '' + value and similar stay banned in both. |
| no-param-reassign | { props: true } | A parameter is the caller's value; assigning to it or to one of its properties is a hidden side effect. |
| no-await-in-loop | on | Iterations that could run together run one after another. for await is allowed. |
| require-atomic-updates | on | total += await p reads total before the await and writes it after, losing any update made in between. |
| default-case-last | on | A default that is not last hides the cases written after it. |
| no-return-assign | always | Even a parenthesised assignment cannot be the returned value. |
| max-depth | { max: 4 } | The rule's own default, written out so a change to it cannot loosen the limit. |
A loop that is sequential by design (migrations that must run in order, a rate-limited API) is exempted by a files-scoped override placed after the shared config, never by an inline disable comment, since noInlineConfig is on:
export default defineConfig(...exadevConfig(), {
files: ['src/migrations/**/*.ts'],
rules: { 'no-await-in-loop': 'off' },
});The lighter option: the plugin named export
For a project that wants only this package's own rules without the full type-checked bundle, import the named plugin export and wire rules individually:
// eslint.config.ts
import { defineConfig } from 'eslint/config';
import { plugin } from '@exadev/eslint-config';
export default defineConfig(
// ...your own config...
{
files: ['src/**/*.ts'],
ignores: ['src/index.ts'],
plugins: { exadev: plugin },
rules: {
'exadev/no-non-barrel-reexport': 'error',
},
},
);Or use one of plugin's two bundled configs to enable a whole set at once:
import { plugin } from '@exadev/eslint-config';
import { defineConfig } from 'eslint/config';
export default defineConfig([
{
files: ['**/*.ts'],
plugins: { exadev: plugin },
extends: ['exadev/recommended'], // this plugin's own non-type-aware rules, the core robustness rules, plus linterOptions.noInlineConfig — no type-checked rules at all
// or: extends: ['exadev/barrel'], // just the barrel-discipline trio (no-non-barrel-index, no-non-barrel-reexport, no-side-effects-in-index)
},
]);tseslint.config() does not accept string extends (only defineConfig() does); pass the config value directly instead:
import { plugin } from '@exadev/eslint-config';
import tseslint from 'typescript-eslint';
export default tseslint.config(
// ...your own config...
{
files: ['**/*.ts'],
plugins: { exadev: plugin },
extends: [plugin.configs.recommended], // or plugin.configs.barrel
},
);plugin.configs.recommended/plugin.configs.barrel carry no files/ignores and are safe unscoped — no-side-effects-in-index and no-non-barrel-reexport each check context.filename themselves (self-scoping). For a barrel not at src/index.ts, or a project-specific exception, layer an override on top (e.g. { files: ['lib/other.ts'], rules: { 'exadev/no-non-barrel-reexport': 'off' } }) rather than wiring all four rules individually. A package that publishes several entry points declares them through exadev/barrel-policy's entries option instead (see Package entry points), which keeps each entry held to the barrel rules rather than switching them off.
Optional features
| Feature | Default | Control it with |
| --- | --- | --- |
| React & Next.js linting | Auto-detected: on if the relevant peer package is installed | exadevConfig({ react, nextjs }) |
| Gitignore-derived ignores | On if the project has a .gitignore | exadevConfig({ gitignore }) |
| RFC 8785 canonical JSON formatting | Always on | Not optional |
| package.json key ordering | On, unless the project already has a syncpack config | exadevConfig({ packageJsonKeyOrder }) |
| Workspace architecture rules | Off unless given (no sensible default for groups) | exadevConfig({ workspaceArchitecture }) / workspaceArchitectureConfig(options) |
| Turbo rules | Off unless given (only a repository can say it uses turbo) | exadevConfig({ turbo }) / turboConfig(options) |
| Import policy | Off unless given (only a repository can say which imports it forbids) | exadevConfig({ importPolicies }) / importPolicyConfig(policies) |
| Pure modules | Off unless given (only a repository can say which modules are a functional core) | exadevConfig({ pureModules }) / pureModulesConfig(options) |
| Guard and conformance test hygiene | Off unless given (only a repository can say which tests are guards); needs the optional peer @vitest/eslint-plugin | exadevConfig({ testHygiene }) / testHygieneConfig(options) |
| Tooling wiring | Off unless given (only a repository can say it wants its publish checks, root tooling and hooks enforced); the package.json sections need the optional peer @eslint/json | exadevConfig({ toolingWiring }) / toolingWiringConfig(options) |
| Turbo environment variable checking | Auto-detected: on if eslint-plugin-turbo is installed | exadevConfig({ turboEnv }) |
| Required Markdown headings | Off unless given (only a repository can say which documents need which headings); needs the optional peer @eslint/markdown | exadevConfig({ markdownHeadings }) / markdownHeadingsConfig(options) |
| Agent skills and plugin marketplaces | Auto-detected: on if the project has a .claude-plugin/marketplace.json, a skills/<name>/SKILL.md or a plugins/<plugin>/skills/<name>/SKILL.md (symbolic links to those directories count); the SKILL.md rules need the optional peer @eslint/markdown and the manifest rules @eslint/json | exadevConfig({ agentSkills }) / agentSkillsConfig(options) |
Every tri-state option above (true/false/undefined) is passed through the named exadevConfig(options) factory export:
// eslint.config.ts
import { defineConfig } from 'eslint/config';
import { exadevConfig } from '@exadev/eslint-config';
export default defineConfig(
{
languageOptions: {
parserOptions: { project: './tsconfig.json', tsconfigRootDir: import.meta.dirname },
},
},
...exadevConfig({ react: true, nextjs: false }),
// ...your own config...
);exadevConfig takes the options object alone and returns a config array, so your own blocks go after the spread inside defineConfig, as above: defineConfig(...exadevConfig(), { rules: { 'no-console': 'warn' } }) is the default export plus one more block. Passing a block as a second argument is a type error. import exadev from '@exadev/eslint-config' (the default export) is just exadevConfig() called with no arguments.
Optional React and Next.js support
React/hooks/a11y and Next.js rule blocks fold in automatically, with no separate import or config needed, gated on two independent, always-both-required conditions:
The corresponding package must actually be resolvable.
eslint-plugin-react,eslint-plugin-react-hooks,eslint-plugin-jsx-a11y, and@next/eslint-plugin-nextare all optional peer dependencies (peerDependenciesMeta.<pkg>.optional: true) — install only whichever your project actually needs:pnpm add -D eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y # React support pnpm add -D @next/eslint-plugin-next # Next.js supportIf none of these resolve,
@exadev/eslint-config's default export is byte-for-byte identical to the plain TypeScript ruleset — nothing about the base package changes.If you run
eslint-plugin-depend'sban-dependencieson yourpackage.json, it reportseslint-plugin-react, which the module-replacementspreferredpreset lists with a suggested alternative; the other React and Next.js peers are not listed. This package's React support is built oneslint-plugin-react, and it does not bundleeslint-plugin-depend, so allow the package in your own block.allowedtakes exact package names, and the block needs nolanguageof its own becauseexadevConfig()already lintspackage.jsonasjson/json:import { defineConfig } from 'eslint/config'; import depend from 'eslint-plugin-depend'; import { exadevConfig } from '@exadev/eslint-config'; export default defineConfig(...exadevConfig(), { files: ['package.json'], plugins: { depend }, rules: { 'depend/ban-dependencies': ['error', { allowed: ['eslint-plugin-react'] }] }, });For React specifically, the file must actually be
.jsx/.tsx. The React/hooks/a11y rule block is scoped tofiles: ['**/*.jsx', '**/*.tsx'], so even ifeslint-plugin-reactis resolvable only incidentally (e.g. hoisted as a transitive dependency of something unrelated in a monorepo, with zero real JSX anywhere in the linted project), its rules never match a file that isn't JSX.@next/eslint-plugin-next's own block carries no such glob: its own presence is already an unambiguous signal (nothing installs it except a real Next.js project). The server component boundary rules added beside it are scoped to the same JSX files.
React support pairs eslint-plugin-react's flat/recommended with its own flat/jsx-runtime config, turning react/react-in-jsx-scope and react/jsx-uses-react back off. flat/recommended alone assumes the classic runtime, where every file using JSX needs import React in scope; the automatic JSX runtime (the default since React 17, and the only mode Next.js's own compiler supports) needs no such import. Without this pairing, a consumer on the automatic runtime would see react/react-in-jsx-scope fire on every JSX file.
Explicit control, for anyone who doesn't want to rely on auto-detection:
plugin.configs.react/plugin.configs.nextjs— explicit tier selection, mirroringplugin.configs.recommended/.barrel. Unlike those two, selecting.react/.nextjsis itself an explicit request: it throws a clear, actionable error if the underlying peer isn't installed, rather than silently returning nothing.import { defineConfig } from 'eslint/config'; import { plugin } from '@exadev/eslint-config'; export default defineConfig( // ...your own config... { files: ['**/*.tsx'], plugins: { exadev: plugin }, extends: [plugin.configs.react], // throws if eslint-plugin-react isn't installed }, { files: ['**/*.ts', '**/*.tsx'], plugins: { exadev: plugin }, extends: [plugin.configs.nextjs], // throws if @next/eslint-plugin-next isn't installed }, );exadevConfig({ react, nextjs })— see the tri-state table below.
| Value | React (options.react) | Next.js (options.nextjs) |
| --- | --- | --- |
| true | Force on — throws if eslint-plugin-react isn't resolvable | Force on — throws if @next/eslint-plugin-next isn't resolvable |
| false | Force off — always [], no resolution attempted | Force off — always [], no resolution attempted |
| undefined / omitted | Auto-detect (the default) | Auto-detect (the default) |
Compatibility note: a consumer who already has eslint-plugin-react/@next/eslint-plugin-next resolvable for unrelated reasons (e.g. hoisted in a monorepo) and writes .jsx/.tsx files may see new rule activity the moment they upgrade to a version of this package that ships React/Next.js support, with zero action on their part. This is the normal, widely-accepted ESLint-ecosystem convention that adding rules to a shared/recommended config is a minor bump even though it can newly trip an existing --max-warnings 0 gate — not a breaking change. Use the react/nextjs options above to force it off explicitly if needed.
Server component boundary
Props a server component passes to a client component must be serialisable, and two easy mistakes surface only at runtime in a production build. The Next.js preset (auto-detected, exadevConfig({ nextjs: true }) or plugin.configs.nextjs) therefore adds a block for .jsx and .tsx files enabling two rules. Both apply only to a file without a top-level "use client" directive, so a client file is never reported; neither needs type information.
exadev/no-non-serialisable-server-propreports a JSX attribute named innames(default['component']) whose value is not data. Data is a literal (not a regular expression), a template literal, object or array of data,undefined, a unary expression (-x,!x,typeof x, which always yields a primitive), or a JSX element, which React serialises. An identifier, member access, call, function, class, spread, or object member holding a function is reported, since it may be a function or component reference. Passingcomponent={Icon}to a client component fails; passing a string key orcomponent={<Icon />}does not.exadev/no-external-member-jsx-tagreports every member tag (<Lib.Icon>,<Lib.Icons.Home>) whose root identifier is bound by an import from a non-relative source, whether a namespace, default, named orimport x = require()binding. Whether a library attaches statics after export cannot be worked out from one file, so the rule is deliberately over-broad. A relative import is the project's own code and is not reported; an alias to project code such as@/uilooks like a package, so list it inallowSources.
Both are approximations. They report a file without the directive that is only ever imported by client code (add the directive), a server-safe <Ctx.Provider> from an imported context (list it in allowTags), and a component passed to an element that is itself a server component (list the element in allowElements). Options, by rule:
| Rule | Option | Meaning |
| --- | --- | --- |
| no-non-serialisable-server-prop | names | Prop names whose value must be data. Replaces the default ['component']. |
| no-non-serialisable-server-prop | allowElements | JSX element names as written (Link, Lib.Icon) whose props are not checked. |
| no-external-member-jsx-tag | allowSources | Import specifiers, in the specifier pattern form (each also selects everything beneath it), whose member tags are not reported. |
| no-external-member-jsx-tag | allowTags | Tags as written (Ctx.Provider) that are not reported. |
The preset enables both at error with the defaults. To tune them, add a later block that sets the rule again for the same files:
{
files: ['**/*.tsx'],
rules: {
'exadev/no-non-serialisable-server-prop': ['error', { names: ['component', 'icon'], allowElements: ['Link'] }],
'exadev/no-external-member-jsx-tag': ['error', { allowSources: ['@/ui'], allowTags: ['ThemeCtx.Provider'] }],
},
}Gitignore-derived ignores
exadevConfig()'s default output includes an ignores block derived directly from your project's own .gitignore (via @eslint/config-helpers's includeIgnoreFile), so a generated directory your .gitignore already knows about (dist/, coverage/, a tool's own report output) is never linted, without hand-duplicating that list in eslint.config.ts too. This closes a real gap: a .gitignored directory that nothing previously linted broadly enough to reach could still get linted the moment a wide-reaching rule (this package's own bundled RFC 8785 JSON canonicalization, say) started matching every file its glob covers.
| Value | options.gitignore |
| --- | --- |
| true | Force on — throws if no .gitignore exists |
| false | Force off — always [], no resolution attempted |
| undefined / omitted | Auto-detect (the default): on if the project has a .gitignore, silently off if it doesn't (nothing to read from a project with no version control set up yet) |
Needs no peer to install — @eslint/config-helpers is bundled into this package's own build.
RFC 8785 canonical JSON formatting
Every JSON file is linted against eslint-plugin-json-canonical v2 — plain UTF-16 code-unit key ordering, canonical number formatting, canonical string escaping, and (as of that plugin's own v2) pretty-printed layout (2-space indentation, one member/element per line, a trailing newline), per RFC 8785. This is bundled unconditionally, the same way jsdoc/tsdoc support is: eslint-plugin-json-canonical is a plain dependency of this package, so every consumer already has it. There is no option to turn it off.
The plugin's own full-canonicalization rule (no-insignificant-whitespace, which collapses a document to a single compacted line with no whitespace at all) is deliberately not part of the config this package extends — it stays available for a consumer to opt into directly for their own genuine canonicalization pass (hashing, signing, byte-for-byte comparison).
**/*.jsonc, **/tsconfig*.json, and **/turbo.json get the plugin's configs.contentOnlyJsonc instead of the plain-JSON config: they genuinely carry comments (TypeScript and turbo both accept them), which @eslint/json's json/json language has no concept of and fails to parse, and neither pretty-printing nor whitespace-collapsing has a well-defined answer for a comment's own attachment to a member once its surrounding whitespace is rewritten. Content canonicalization (key order, number/string formatting) still applies to these files under json/jsonc.
**/package.json gets everything the plain-JSON config gives every other file — including pretty-printed layout — except json/sort-keys, turned back off in its own override block, since its key order is the separate, syncpack-aware concern the next section covers.
Stylistic comment, class-member and JSX rules
A hand-picked subset of @stylistic/eslint-plugin is bundled unconditionally, the same way jsdoc/tsdoc and RFC 8785 JSON support are: @stylistic/eslint-plugin is a plain dependency of this package, so every consumer already has it, and every rule below matches purely on comment shape, statement/class-member placement, or JSX prop/tag conventions, never on formatting (indentation, quotes, semicolons, trailing commas, line wrapping, bracket spacing), which stays Prettier's job in every consumer of this package. None of these rules appears in eslint-config-prettier's own disabled-rules list.
multiline-comment-styleat'bare-block', through this package's own wrapperexadev/multiline-comment-stylerather than the plugin's rule id: a run of//lines becomes one/* ... */block. The wrapper exists because upstream does not yet treatTODO/FIXMElines as directives (eslint-stylistic/eslint-stylistic#1287), norcspell:*,biome-ignoreor#region/#endregion, and its fixer folds them into the merged block. Upstream already keeps its own directives (prettier-ignore,c8 ignore/v8 ignore,istanbul ignore,@ts-expect-error/@ts-ignore/@ts-nocheck/@ts-check, triple-slash reference/AMD directives and the rest of its list) as standalone lines since PR #1251. A folded marker is not cosmetic:exadev/prefer-doc-commentleaves a block containing a directive alone, so an exported declaration whose leading run held aTODOwould silently lose its doc comment. The wrapper runs the upstream rule unchanged (options, defaults, messages and fixer are upstream's), except that every lineexadev/prefer-doc-commenttreats as a directive is hidden from its grouping, so such a line breaks a run exactly as an upstream directive does and the prose on each side is converted on its own. The upstream fixer writes a bare\ninside the merged block in a CRLF file, and the wrapper does not change that. The wrapper strips trailing whitespace from the text the upstream fixer writes (upstream leaves it on blank lines inside a rewritten block), and a managed-region marker (a comment of exactly<word>:<word>:startor<word>:<word>:end, such ascontent:claude:start) is treated as a directive, since the tool that owns it finds it by its exact line.spaced-comment: requires a space after////*, without fighting a/**-opening doc comment or a shebang line. Adds{ block: { markers: ['!'] } }on top of the bare default so a/*!license/banner block is not flagged either. A triple-slash reference/AMD directive is exempted by the rule itself in both its spaced form (/// <reference types="..." />, TypeScript's own compiler-emitted spelling) and its no-space form (///<reference types="..." />, also valid TypeScript syntax); before@stylistic/eslint-plugin6.0.0,--fixrewrote the no-space form into a broken// /<reference ...>comment (ExaDev/eslint-config#47). Also adds{ line: { markers: ['#', '#region', '#endregion'] } }: without it, the bare default rewrites a//# sourceMappingURL=...///# sourceURL=...source-map comment into// # sourceMappingURL=..., which browsers and Node no longer recognise, and a bareline: { markers: ['#'] }alone would instead rewrite an unspaced//#region///#endregioneditor fold marker into//# region, which VS Code's own folding regex no longer matches. Listing all three markers together, confirmed directly against the installed rule, leaves every one of those four shapes untouched.lines-between-class-membersat its bare default: a blank line between class members, except after a.d.ts-style method overload signature.line-comment-positionat'above': a//comment belongs above the code it describes, never trailing beside it on the same line. Not autofixable; a flagged trailing comment needs moving by hand. A trailing// cspell:disable-lineis exempt (ignorePattern): cspell honours that directive only on the line it suppresses, so moving it above, as the report demands, would silently disable spell-checking for the wrong line. Every other directive this package recognises applies to the line(s) below it and is correctly relocated.padding-line-between-statements: a blank line is required after the last statement of a directive prologue (not between two consecutive directives), after the last CommonJS or ES import in a run (not between two consecutive imports), and before areturnstatement.jsx-curly-brace-presence,jsx-pascal-case, andjsx-self-closing-comp, each at its own bare default: none of the three has any dependency oneslint-plugin-reactor React itself (confirmed directly against@stylistic/eslint-plugin's ownpackage.json, whosepeerDependenciesareeslintandoxlint, both optional), since each matches purely on a JSX AST node shape and is a structural no-op on every non-JSX file.
JSX's shorthand-boolean-prop convention (<Foo enabled /> vs <Foo enabled={true} />) and shorthand-fragment syntax (<>...</> vs <React.Fragment>...</React.Fragment>) are not enforced: neither @stylistic/eslint-plugin's own jsx-shorthand-boolean and jsx-shorthand-fragment nor eslint-plugin-react's react/jsx-boolean-value and react/jsx-fragments are enabled, here or in the optional React support gate above.
This package's own exadev/prefer-doc-comment and exadev/multiline-comment-style rules (see Rules) are wired alongside these, in the same unconditional bundle.
Optional package.json key ordering
exadevConfig({ packageJsonKeyOrder: true }) enables exadev/package-json-key-order for **/package.json, requiring the same key order syncpack format would produce — sortFirst fields (name, description, version, author by default) pinned to the top in that exact order, then every other top-level key alphabetically; and, inside each sortAz-listed field's own object or array value (dependencies, devDependencies, scripts, keywords, and the rest of syncpack's own default list), its members/elements sorted the same way. Confirmed directly against real syncpack@15 output, not assumed from its docs — see this rule's own source comment for the exact reverse-engineering method (a symbol-before-digit-before-letter, case-insensitive comparison syncpack's docs don't specify precisely enough to derive from prose alone).
This exists for a project that wants real package.json canonicalization without installing syncpack, and so a project that already has syncpack never sees the two fight: eslint --fix and syncpack format converge on the identical output.
| Value | options.packageJsonKeyOrder |
| --- | --- |
| true | Force on — throws if @eslint/json isn't resolvable |
| false | Force off — always [], no resolution attempted |
| undefined / omitted | Auto-detect (the default): on unless the project already has a syncpack config (a .syncpackrc*/syncpack.config.* file, or a "syncpack" key in its own package.json), since syncpack already produces this exact order for free |
Like React/Next.js support, this needs its own optional peer resolvable — @eslint/json is declared in peerDependenciesMeta as optional, so install it in your project with pnpm add -D @eslint/json — and, unlike them, also needs its json/json language registered for the file (this option's own config block does that for you; nothing extra to wire up).
Bundled into exadevConfig()'s default output the same way React/Next.js auto-detection is — packageJsonKeyOrder: true/false only forces the tri-state explicitly, it isn't the only way to reach it. Not part of plugin.configs.recommended, and not available as a plugin.configs.packageJsonKeyOrder explicit-tier config the way .react/.nextjs are, since wiring it through plugin.configs would need plugin.ts and this option's own config builder to import each other.
Rules
| Rule | Fixable | Description |
| --- | --- | --- |
| barrel-policy | | Umbrella rule selecting a whole index-file barrel policy. One { mode } option covers the four barrel rules below, and an entries option declares a package's other entry files as barrels. See Barrel policy. |
| no-index-files | | Bans any index.* file outright (mode 1). The strictest policy. |
| no-non-barrel-index | | Only src/index.ts may be named index.* — any other index.ts/.js/etc would be silently selected by a consumer's bare directory import. |
| no-non-barrel-reexport | ✓ | Re-exports belong only in a barrel. Catches the split form across two statements (import { x } from './y'; export { x }; or export default x;) which no AST selector alone can match. Autofix deletes the export and the now-pointless import when it was the import's only use. Self-scopes away from any index file. |
| no-side-effects-in-index | | A barrel may contain only re-export statements — nothing that could execute at import time. Self-scopes to any index file. |
| barrel-direct-siblings-only | | A barrel may re-export only from a direct sibling (./module), never a nested path, parent, or bare package specifier (mode 3). |
| no-control-flow | | Bans if/switch/loops/the ternary operator outright. Not part of recommended or barrel — ordinary code legitimately needs control flow, so this is opt-in, wired via a consumer's own files glob for the specific packages that want it (a composition-root package selecting an adapter/strategy by a validated key, say): a lookup table replaces a branch, a declarative array method (map/filter/some/every/...) replaces a loop. Requires no type information. See also Pure modules, which can add it to a block, and a complexity ceiling for a softer limit. |
| no-pointless-reassignment | ✓ | Flags a const alias that adds no transformation (const foo = bar where both sides are plain identifiers). Autofix rewrites every read to the original name and deletes the declaration. Still reported but deliberately not auto-fixable where collapsing the alias would change meaning: an explicit type annotation (const exhaustive: never = item — the annotation is the point), a read where the original name is shadowed, a read as a shorthand object property, more than one declarator in the statement, or a source that is written to anywhere. An alias that is itself part of the module's exported surface (export const alias = original;, a later export { alias }/export { alias as other }, or export default alias;) is neither reported nor fixed at all, since collapsing it would rename or delete a binding every importer of this module depends on. |
| no-object-assign | ✓/suggestion | Object.assign skips the type-checking object spread gets — it doesn't check a source object's properties against the target's declared types. A fresh object-literal target autofixes to { ...target, ...source }; mutating an existing reassignable binding offers a suggestion only (changes the object's identity); a const binding or a non-statement call site gets a plain report with no fix. |
| no-mutable-union-array-param | ✓ | A union-typed array parameter can be mutated with a value the caller's narrower array never declared. A function parameter typed as an array of a union ((string \| number)[]) accepts a narrower caller array (number[]) by covariance; calling push/unshift/splice/fill/copyWithin on it can then insert a value the caller's own array was never declared to hold. Autofix marks the parameter readonly, turning the mutating call into a real compile error to resolve deliberately. Requires no type information. |
| prefer-readonly-array-param | ✓ | Every non-readonly array/tuple parameter should be readonly. A narrower, safely-autofixable sibling of @typescript-eslint/prefer-readonly-parameter-types scoped to array/tuple parameter shapes only: fires unconditionally on every non-readonly array or tuple parameter, regardless of whether the function body mutates it, in any parameter position (a plain identifier, a rest parameter, a default-valued parameter, or a constructor parameter property) and any function-like shape (a concrete function/arrow/method, or a declaration-only ambient function, interface method, function type alias, call/construct signature, or abstract/ambient class method). A union containing an array/tuple member is fixed on that member alone. Autofix prepends readonly (or renames Array<T> to ReadonlyArray<T>), turning any resulting mutation into a real compile error to resolve deliberately. Requires no type information — registered in both plugin.configs.recommended and the default (type-checked) export. |
| prefer-readonly-object-param | ✓ | A flat object parameter's type should be wrapped in Readonly<...>. The object-shape sibling of prefer-readonly-array-param above, scoped to "flat" object parameters where a shallow fix is provably sufficient: an inline { ... } literal or a reference to a plain named type/interface where every property (and index-signature value, if any) is itself a primitive, a literal/union of primitives, or a callback — with no nested object, array, tuple, Map, Set, class instance, union, intersection, or unconstrained type parameter anywhere in the shape. Autofix wraps the parameter's own type annotation in Readonly<...>, which TypeScript's own deep-readonly check accepts as fully sufficient for a shape this flat. Requires type information — only in the default (type-checked) export, not plugin.configs.recommended — to resolve each property's real type via the checker. |
| no-array-isarray-mutation | | Array.isArray narrowing discards a readonly array's own guarantee. Its type declaration narrows to plain any[], discarding the readonly guarantee of any array type in the narrowed parameter's or local variable's real type — a bare readonly T[], a ReadonlyArray<T>, one behind a type alias, or one alongside other union members — inside the guarded branch; calling push/unshift/splice/fill/copyWithin there can mutate a caller's genuinely readonly array. Recognises the direct if (Array.isArray(x)) guard (braced or not), the early-return/early-throw idiom, &&, the ternary form, and the else-of-a-negated-test form. No autofix: re-adding readonly is a no-op (the guard already discarded it) and rewriting the mutating call into a copy-first pattern is not safely mechanical in the presence of aliasing. Requires type information — only in the default (type-checked) export, not plugin.configs.recommended — specifically to see through a type alias and to catch a bare, non-union readonly array parameter or local variable, neither visible from its own syntax alone. |
| no-map-instanceof-mutation | | instanceof Map narrowing discards a ReadonlyMap's own guarantee. Map is declared as extending ReadonlyMap, so instanceof Map narrows a parameter or local variable whose real type includes a ReadonlyMap — bare, unioned, or reached through a type alias — straight past the readonly guarantee to the full mutable interface; calling set/delete/clear there can mutate a caller's genuinely read-only map. Recognises the direct if (input instanceof Map) guard (braced or not), the early-return/early-throw idiom, &&, the ternary form, and the else-of-a-negated-test form. No autofix: rewriting the mutating call into a copy-first pattern is not safely mechanical in the presence of aliasing. Requires type information — only in the default (type-checked) export, not plugin.configs.recommended. |
| no-set-instanceof-mutation | | instanceof Set narrowing discards a ReadonlySet's own guarantee, straight to the fully mutable Set interface, with no way to preserve the read-only guarantee through the narrowing; calling add/delete/clear there can mutate a caller's genuinely read-only set. Recognises the same guard idioms as no-map-instanceof-mutation above. No autofix, for the same aliasing reason. Requires type information — only in the default (type-checked) export, not plugin.configs.recommended. |
| no-enum-number-widening | | A bare number is accepted anywhere a numeric enum is expected, without checking it is actually one of the enum's members — only a numeric literal gets range-checked by tsc. No autofix: the only provably safe fix is a genuine runtime membership check against the enum's own values, which is a behavioural choice a mechanical fix cannot responsibly make. Requires type information — only in the default (type-checked) export, not plugin.configs.recommended. |
| no-enum-reverse-lookup-widening | suggestion | A numeric enum's reverse lookup can silently type as string for an out-of-range index. Indexing a numeric enum's reverse mapping (Direction[n]) with a bare (non-literal) number, or with a different enum's member, types as plain string for any index, including one outside the enum's actual members, where it genuinely returns undefined at runtime — tsc does not range-check even a numeric literal index here. When the indexed expression is the init of a variable with an explicit : string annotation, a suggestion widens it to : string \| undefined, forcing later uses as a bare string to surface as real compile errors; every other syntactic position gets a plain report with no fix, and no case gets a full --fix autofix. Requires type information — only in the default (type-checked) export, not plugin.configs.recommended. |
| prefer-numeric-sort-compare | suggestion | .sort() on a number array sorts lexicographically by default. A deliberately narrow addition alongside @typescript-eslint/require-array-sort-compare (which already flags any bare .sort()/.toSorted() except on a plain string array, with no fix): when the array's element type is definitively number, a suggestion offers an ascending compare function ((a, b) => a - b), since the default comparator sorts lexicographically ([1, 2, 10].sort() becomes [1, 10, 2]). Not a full autofix — descending order is a real, if less common, alternative intent. Requires type information — only in the default (type-checked) export, not plugin.configs.recommended, since it needs the checker to confirm the array's element type. |
| prefer-options-object-param | suggestion | A run of 2+ trailing optional parameters (?-marked or default-valued) should be bundled into one destructured options parameter, and an optional parameter should not sit directly before a rest parameter. Without this, a caller needing only the last optional parameter must still pass undefined for every optional parameter before it (the motivating case: a 10-parameter constructor with 8 trailing optional ones). The threshold is configurable ({ minTrailingOptional }, default 2). A suggestion (not a full autofix) rewrites the parameter list and inserts a const { ... } = options ?? {}; destructure as the body's first statement; call sites are never rewritten, since the signature edit alone turns every stale positional call site into a real compile error. Still reported, but with no suggestion offered, whenever collapsing the run would not be safe/mechanical: a parameter property in the run, a parameter with no simple resolvable name and explicit type of its own (including a destructured parameter, or one typed only through a separately-declared function-type alias), a decorated parameter, a rest parameter anywhere in the full parameter list, no BlockStatement body at all (an arrow's expression body, or any declaration-only signature — including an ambient .d.ts function, an interface method/construct signature, or an abstract/ambient class method), a @param JSDoc tag naming a parameter in the run, or a parameter/function-scope-local variable already named options. An optional parameter directly before a rest parameter is reported as well, even when it is the only optional one ((options = {}, ...blocks)), because a caller wanting only the rest values must pass a placeholder for it; that report has its own message and no suggestion, since the right shape (the rest values alone, or one object holding the optional value and the rest values) is a design decision. Complements max-params (see "Individual rule tuning" above), which catches the different shape (excessive REQUIRED parameters) this rule is deliberately blind to. Requires no type information — registered in both plugin.configs.recommended and the default (type-checked) export, like prefer-readonly-array-param above; unlike its own prefer-readonly-object-param/prefer-numeric-sort-compare siblings, which genuinely need the checker and so cannot be offered outside the default export at all. |
| prefer-doc-comment | ✓ | A substantial leading comment on an exported declaration should be a doc comment, not a plain ////* */ comment. "Substantial" means 2 or more comment lines, or a single line whose text exceeds a configurable length ({ maxLineLength }, default 80). Covers an exported function declaration, an exported function's own signature (a body-less TSDeclareFunction, an ordinary overload signature and a genuinely ambient one alike, declare function foo(): void; included, since TypeScript never shows either one's own implementation to callers, only the signature itself), an exported const declaration, whatever its initialiser (a function expression or arrow function, an ordinary value such as export const TIMEOUT_MS = 5000;, or none at all in an ambient export declare const x: number;; reported once even when the statement declares several, e.g. export const h1 = () => {}, h2 = () => {};), an exported class declaration, ambient (export declare class) or ordinary alike (TypeScript strips only an ambient class's own MEMBER bodies, never its declaration shape, so its leading comment documents the identical public contract an ordinary exported class's does), an exported class's public (non-private/protected/#-private) method (covering both a method's own overload signature and its trailing implementation) and public abstract method (abstract m(): void;, needing no equivalent overload-implementation exemption of its own, since TypeScript's own grammar never lets an abstract method carry a body at all), an exported class's public function/arrow-valued property (the class-member equivalent of the function-initialised const shape above), an exported interface/type-alias declaration, an exported enum declaration (const enum alike; never an individual member, the identical reason an interface's members are never individually checked), an exported namespace/module declaration (ambient or ordinary alike, at any nesting depth whose enclosing namespaces are all exported themselves), and a default-exported expression (export default (): number => 1;, export default 42;; a default-exported function/class declaration or body-less signature is covered by its own shape above and reported exactly once, never twice); a non-exported declaration is never reported, regardless of its comment. A TypeScript function/method overload set's own body-carrying IMPLEMENTATION signature is never reported either, however substantial its own comment: TypeScript never shows that signature to callers at all, only the separate overload signatures above it (a body-less TSDeclareFunction for a function, written without declare, or a MethodDefinition whose own value is TSEmptyBodyFunctionExpression for a class method) are ever checked against a call site, and both of those are themselves reported like any other declaration in this rule's scope, as the overload set's own real public contract; a comment directly above the implementation is instead internal reasoning about how the overloads are actually realised, never a public contract. The implementation is detected via ESLint's own scope analysis for a function (the overload signatures and the implementation all share one Variable) and, for a class method, via an EARLIER (source-order), same-static-ness, same-key signature sibling: a same-named static/instance pair is never one overload set to TypeScript itself, and a same-named signature declared AFTER the implementation belongs to a different, later member, never the one the implementation itself realises, so neither is ever mistaken for the implementation's own overload signature. A trailing comment on the previous line of code (const x = 1; // note) is never treated as the next declaration's own leading comment. A directive-shaped line (the full ESLint directive/config-comment family, eslint-disable/eslint-disable-line/eslint-disable-next-line/eslint-enable/eslint/eslint-env/global/globals/exported, matched case-sensitively, exactly as ESLint's own directive parser matches them, each requiring real whitespace or end-of-string immediately after the keyword rather than a bare word boundary, so an ordinary compound word such as eslint-plugin-x is never mistaken for one, and, on a // Line comment specifically, recognised only as eslint-disable-line/eslint-disable-next-line, the two labels ESLint itself honours there; every other member of the family is a directive only in Block form, matching what ESLint itself does; @ts-expect-error/@ts-ignore/@ts-nocheck/@ts-check, the ts-* markers matched with or without their own leading @; TODO/FIXME, matched case-insensitively when all-uppercase or immediately followed by :/( (todo:, fixme(scope):), never a Todo/Fixme opening ordinary prose; prettier-ignore; c8 ignore/v8 ignore/istanbul ignore/node:coverage ignore/node:coverage disable/node:coverage enable; cspell:disable/cspell:disable-line/cspell:disable-next-line/cspell:enable (never cspell's own ignore/words directives, which name dictionary words rather than suppressing a stretch of text); biome-ignore; #region/#endregion, an editor folding marker; and a managed-region marker, a comment of exactly <word>:<word>:start or <word>:<word>:end such as content:claude:start, which a tool locates by its exact line) found anywhere in a // run is never itself merged into the fix: only the prose segment directly adjacent to the declaration, the run of lines after the LAST such directive, is ever reported and converted; every earlier segment, and every directive line itself, is left completely untouched, since an earlier segment sits on the far side of a directive from the declaration and documents whatever the directive itself demarcates, never the declaration below it; a directive seated directly above the declaration itself is transparent to this split rather than a boundary of it, since group assembly skips past it before the run is ever collected, so the prose above it is still reported and converted, with the directive preserved untouched in place, still functional, directly above the declaration; a directive found inside an already-consolidated Block comment leaves the whole comment alone, since a partial fix cannot safely be sliced out of one physical comment node. A /// triple-slash reference/AMD directive (/// <reference types="..." />) is recognised separately, by its own un-stripped comment value rather than this same pattern, and excluded from the fix the same way. An existing /**-opening doc comment, or a /*! license/banner block, is left alone regardless of length. Autofix rewraps the comment's existing text into a /** ... */ block, one line per original logical line as this rule's own fixer writes it, preserving each line's own indentation beyond the delimiter's single conventional space (never flattening a nested example or sub-list to its neighbours' level), and unwraps a hand-written starred block's (/* ... */ with its own leading * per line) marker rather than doubling it against the fixer's own. This describes this rule's own fixer alone, not a guarantee that exadevConfig()'s combined output preserves that text verbatim: a bundled sibling rule's own fixer can still rewrite it further in the same --fix run, which is exactly why the fix is withheld below for
