README.adoc

Perfective ESLint Config

@perfective/eslint-config provides a shareable ESLint configuration that is used for the development of the @perfective packages. These rules are primarily configured for TypeScript projects.

In addition to the core ESLint, @typescript-eslint, and ESLint Stylistic plugin rules, @perfective/eslint-config includes configurations for the ESLint plugins:

• eslint-plugin-array-func;

• eslint-plugin-cypress (optional);

• eslint-plugin-deprecation;

• eslint-plugin-eslint-comments;

• eslint-plugin-import;

• eslint-plugin-jest (optional);

• eslint-plugin-jest-dom (optional);

• eslint-plugin-jest-formatting (optional, required if eslint-plugin-jest is installed);

• eslint-plugin-jsdoc;

• eslint-plugin-node;

• eslint-plugin-prefer-arrow;

• eslint-plugin-promise;

• eslint-plugin-rxjs (optional);

• eslint-plugin-simple-import-sort;

• eslint-plugin-sonarjs;

• eslint-plugin-testing-library (optional);

• eslint-plugin-unicorn.

To simplify configuring ESLint support in the IDEs and editors, the severity of all fixable rules is a warning. In addition, it allows distinguishing errors that have to be fixed manually from issues that will be fixed automatically.

Setup

1. Require @perfective/eslint-config and its peer dependencies as dev dependencies

   npm install --save-dev \
       @perfective/eslint-config \
       @babel/eslint-parser \
       @stylistic/eslint-plugin \
       @typescript-eslint/eslint-plugin \
       @typescript-eslint/eslint-plugin-tslint \
       @typescript-eslint/parser \
       eslint \
       eslint-import-resolver-typescript \
       eslint-plugin-array-func \
       eslint-plugin-deprecation \
       eslint-plugin-eslint-comments \
       eslint-plugin-import \
       eslint-plugin-jsdoc \
       eslint-plugin-node \
       eslint-plugin-prefer-arrow \
       eslint-plugin-promise \
       eslint-plugin-simple-import-sort \
       eslint-plugin-sonarjs \
       eslint-plugin-unicorn \
       tslint

2. Install optional peer dependencies that add linting rules for the tools you use.

   npm install --save-dev \
       eslint-plugin-cypress \
       eslint-plugin-jest \
       eslint-plugin-jest-dom \
       eslint-plugin-jest-formatting \
       eslint-plugin-rxjs \
       eslint-plugin-testing-library

   Warning

   The eslint-plugin-jest-formatting module is required, if the eslint-plugin-jest module is installed.

   The @perfective/eslint-config automatically includes rules for these plugins, if the dependency is installed.

3. Require the configuration in your root .eslintrc.js.

   module.exports = {
       extends: [
           '@perfective/eslint-config',
       ],
   };

4. *.d.ts files and dist directories are ignored by the configuration. node_modules and dot-files are ignored by the eslint. If more directories or file types need to be ignored, see the .eslintignore file docs.

Rules Configuration Extension Functions

Some rules have complex configuration objects or arrays that are not merged but are completely overridden by ESLint. Therefore, it requires copying and pasting a rule config instead of just extending it. Maintaining rules updates is challenging and is simplified by the custom config functions.

These functions and related types are exported in @perfective/eslint-config/rules and match the rule name in camelCase. If you need an extended configuration, you can use these functions in the .eslintrc.js file:

const rules = require('@perfective/eslint-config/rules'); // (1)

module.exports = {
    extends: ['@perfective/eslint-config'],
    rules: {
        'simple-import-sort/imports': ['warn', rules.simpleImportSortImports([
            '@perfective',
        ])],
    },
};

1. Framework-specific packages, based on @perfective/eslint-config, re-export all the rules. So rules should be required from those packages for correct node_modules resolution.

Supported Rules

• simpleImportSortImports(internal) — allows to splice internal scope packages imports sorting for the simple-import-sort/imports rule.

• typescriptEslintNamingConvention(extensions) — extends configuration for the @typescript-eslint/naming-convention rule.

• typescriptEslintTslintConfig(rules, directories) — overrides rules and provides custom directories for the @typescript-eslint/tslint/config rule.

• unicornPreventAbbreviations(replacements, options) — extends and overrides the list of replacements and options for the unicorn/prevent-abbreviation rule.

TSLint

ESLint and its plugins replace most of the TSLint rules. Yet, a few rules still need to be supported. TSLint rules are executed using the ESLint Plugin TSLint.

eslint-plugin-tslint provides only one rule @typescript-eslint/tslint/config that configures all the remaining TSLint rules, so in order to override some of them, use the typescriptEslintTslintConfig() config function from the '@perfective/eslint-config/rules':

import { typescriptEslintTslintConfig } from '@perfective/eslint-config/rules';

export = {
    rules: {
        '@typescript-eslint/tslint/config': ['error', typescriptEslintTslintConfig({
            'no-default-import': false, // (1)
        })],
    }
}

1. Overrides only one of the rules while keeping all others set by default.

Internals

The rules for each plugin are described in the ./src/rules/{plugin} subdirectories, where the {plugin} is the name of the plugin (after the eslint-plugin- prefix). Each configuration is exported from the ./index.ts file and is organized as a partial ESLint config. It should contain the plugin name and the list of the rules, sorted alphabetically. When a plugin’s documentation groups rules, each group is configured in a separate file and then extended in the ./index.ts file.

The final configuration extends each plugin configuration on a file-type basis.

Roadmap

• Add the @perfective/eslint-plugin with the rules for working with the @perfective packages.

• Replace all TSLint rules with ESLint rules.