@aarongoldenthal/eslint-config-standard/README.md

Standard ESLint configuration settings

# @aarongoldenthal/eslint-config-standard

## Summary

Custom ESLint configuration for all projects. Includes flat-config formatted
configurations compatible with ESLint v9+ for the following:

| Plugin Name                                       | Config name                                                                | Rule Prefix  |
| ------------------------------------------------- | -------------------------------------------------------------------------- | ------------ |
| `eslint`                                          | [`base-configs`](./base-configs.js)                                        | none, `core` |
| `@eslint-community/eslint-plugin-eslint-comments` | [`eslint-comments-config`](./eslint-comments-config.js)                    | `comments`   |
| `eslint-plugin-jest`                              | [`jest-config`](./jest-config.js)                                          | `jest`       |
| `eslint-plugin-jsdoc`                             | [`jsdoc-config`](./jsdoc-config.js)                                        | `jsdoc`      |
| `eslint-plugin-n`                                 | [`node-config`](./node-config.js)                                          | `node`       |
| `eslint-plugin-playwright`                        | [`playwright-config`](./playwright-config.js)                              | `playwright` |
| `eslint-plugin-promise`                           | [`promise-config`](./promise-config.js)                                    | `promise`    |
| `eslint-plugin-unicorn`                           | [`unicorn-configs`](./unicorn-configs.js), [`esm-config`](./esm-config.js) | `unicorn`    |
| `eslint-plugin-vitest`                            | [`vitest-config`](./vitest-config.js)                                      | `vitest`     |

As flat configs, the package defines all required plugins/configurations as
`dependencies`. Since flat config allows flexibility in the rule prefixes (that
is, they don't have to match the plugin name), the rules prefixes are adapted
in some cases to be more intuitive or readable. Since they may be combined, and
flat config doesn't allow nested arrays of rules, file names that are singular
export a single config object (for example `jsdoc-config`), and file names
that are plural export an array of config objects (for example `base-configs`).

The `core` prefix has only one rule, `core/complexity`, that has a higher threshold.
This provides a secondary check for cases where the lower threshold in the `complexity`
rule is disabled, which otherwise allows unbounded complexity. Since re-use of core
rules is an experimental capability, this must be enabled with environment variable
`ENABLE_ESLINT_CORE_RULE_DUPLICATES=true`.

Most rule configurations are applicable to files matching `'**/*.{js,mjs,cjs}'`. The
following configurations are exceptions and are applicable to files as noted:

- `base-configs` sets `sourceType` to `commonjs` for `*.js`/`*.cjs` files and
  `module` for `*.mjs` files.
- `base-configs` includes a config that disables some rules for test files
  matching any of the following test patterns (for example `max-lines`,
  `max-lines-per-function`).
- `jest-config` applies rules to files matching
  `'**/__tests__/**/*.{js,mjs,cjs}'` or `'**/?(*.)+(spec|test).{js,mjs,cjs}'`.
- `vitest-config` applies rules to files matching
  `'**/__tests__/**/*.{js,mjs}'` or `'**/?(*.)+(spec|test).{js,mjs}'`.
- `playwright-config`: applies rules to files matching `'**/*.pwtest.{js,mjs,cjs}'`,
  which differentiates them from Jest/Vitest test files.
- `unicorn-configs` includes a config that disables some rules for test files
  (matching any of the following test patterns), and applies some ESM-specific
  rules only applicable to `*.mjs` files.

With ESLint v9 the majority of formatting rules are deprecated and removed from
`base-configs`, but the `eslint-config-prettier` package is included and can be
added to the config if `prettier` is also being used to ensure it takes priority
for formatting.

There is also an `esm-config` included for projects using ES modules instead of
CommonJS modules. This config sets `sourceType` to `module` for `*.js` files and
includes `unicorn-config` ESM-specific rules.

### Usage

This module is now pure ESM, so must be called from an ESM file, either
`eslint.config.js` (if the project is ESM) or `eslint.config.mjs` (if the
project is CJS).

There is a `recommended` configuration for CJS with all plugin configurations
enabled except `vitest-config` (it does include `jest-config`, and applies
ESM-specific rules to `*.mjs files`). To configure `eslint.config.mjs` with
this configuration:

```js
import { defineConfig, globalIgnores } from 'eslint/config';
import recommendedConfig from '@aarongoldenthal/eslint-config-standard/recommended';

export default defineConfig([
  recommendedConfig,
  globalIgnores(['.vscode/**', 'archive/**', 'node_modules/**', 'coverage/**'])
]);
```

Note the optional `ignores` config that can be added last to ignore certain
directories.

There is also a `recommended-esm` configuration that's the same as the
`recommended` config, but includes the `vitest-config` instead of the
`jest-config`, and also the `esm-config` (applicable to `*.js` files).
It can be configured with:

```js
import { defineConfig, globalIgnores } from 'eslint/config';
import recommendedConfig from '@aarongoldenthal/eslint-config-standard/recommended-esm';

export default defineConfig([
  recommendedConfig,
  globalIgnores(['.vscode/**', 'archive/**', 'node_modules/**', 'coverage/**'])
]);
```

To configure `eslint.config.js` with individual plugins, see the
[`recommended`](./recommended.js) or
[`recommended-esm`](./recommended-esm.js) configurations as examples.

Notes:

- If used, the `base-configs` should be included after other configurations,
  except `esm-config` and `prettier`, so those settings take precedence.
- The `jest-config` and `vitest-config` have the same file applicability, so
  only one should be used.
- If used, the `esm-config` should be configured after all functional rules
  to ensure the overridden settings take precedence.
- If used, the `prettier` config should be included last to take priority in
  disabling the applicable rules from all other configurations.