@aarongoldenthal/eslint-config-standard

Summary

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

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. Configs may be single configs or arrays of configs, as appropriate, so they should be added using the ESLint utility function defineConfig(), which accommodates both types.

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 turned off, 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 all JavaScript and TypeScript files (matching '**/*.{js,mjs,cjs,ts,mts,cts}'). The following configurations are exceptions and are applicable to files as noted:

• base-config sets sourceType to commonjs for *.{js,cjs,ts,cts} files and module for *.{mjs,mts} files.
• base-config 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,ts,mts,cts}' or '**/?(*.)+(spec|test).{js,mjs,cjs,ts,mts,cts}'.
• vitest-config applies rules to ESM files matching '**/__tests__/**/*.{js,mjs,ts,mts}' or '**/?(*.)+(spec|test).{js,mjs,ts,mts}'.
• playwright-config: applies rules to files matching '**/*.pwtest.{js,mjs,cjs,ts,mts,cts}', which differentiates them from Jest/Vitest test files.
• unicorn-config 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,mts} files.
• typescript-eslint-config applies typescript-eslint rules to JavaScript and all TypeScript files. Some of these rules extend core ESLint rules, so those core ESLint rules are turned off in this config to avoid conflicts. It also applies TypeScript-specific rules to TypeScript files only, and configures the @typescript-eslint/parser set to use the closest tsconfig.json file. For rules that are ESM/CJS specific, it assumes *.{js,ts} files are ESM, which differs from base-config. To ensure proper rule overrides, this config should be applied after base-config and esm-config.

With ESLint v9 the majority of formatting rules are deprecated and removed from base-config, 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, although it should be included last.

There is also an esm-config included for projects using ES modules instead of CommonJS modules. This config sets sourceType to module for *.{js,ts} 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 are three versions of recommended configurations covering CommonJS, ESM, and TypeScript, and the individual configurations can be manually configured as well.

recommended configuration

The recommended configuration is for CommonJS with all plugin configurations enabled except vitest-config (it does include jest-config) and typescript-eslint-config. It does apply ESM-specific rules to *.{mjs,mts} files. The rules are applicable to all JavaScript and TypeScript files, but don't require TypeScript (no rules with types). To configure eslint.config.mjs with this configuration:

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

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

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

recommended-esm configuration

The recommended-esm configuration is the same as the recommended config, but for ESM. It includes the vitest-config instead of the jest-config, and also the esm-config (applicable to *.{js,ts} files), but doesn't include typescript-eslint-config. The rules are also applicable to all JavaScript and TypeScript files, but don't require TypeScript (no rules with types). It can be configured with:

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

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

recommended-ts configuration

The recommended-ts configuration is the same as the recommended-esm config, but also includes typescript-eslint-config, and therefore requires TypeScript (an optional peer dependency) and a tsconfig.json file. It can be configured with:

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

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

Using individual configurations

To configure eslint.config.js with individual plugins, see the recommended* configurations as examples.

Notes:

• If used, the base-config should be included after other configurations, except esm-config, typescript-eslint-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 JavaScript rules to ensure the overridden settings take precedence.
• If used, the typescript-eslint-config should be configured after all other 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.