ESLint configuration

The ESLint configuration base for our typescript projects.

Plugins and tools

• @typescript-eslint/eslint-plugin
• @typescript-eslint/parser
• eslint-config-airbnb-base
• eslint-config-airbnb-typescript
• eslint-plugin-import

Installation

npm<v7 or Yarn v1

On npm versions prior to 7, or when using Yarn V1, you'll have to install both eslint and this package, as these package managers do not automatically install peer dependencies:

# npm:
npm install --save-dev eslint @pxlwidgets/eslint-config
# yarn:
yarn add    --dev      eslint @pxlwidgets/eslint-config

For the best compatibility, remove the direct eslint dependency when your project moves to npm >= 7, see below.

npm >= 7 (node >= 15)

As of npm v7, peer dependencies are automatically installed, so only installing this package suffices:

npm install --save-dev @pxlwidgets/eslint-config

Usage

Add the package name to the extends array in your ESLint config file (json version below). You'll also need to specify the location of your application's tsconfig.json file so that @typescript-eslint knows what compiler options your project uses for Typescript. The below snippet is a good starting point for a tsconfig.json file in most Typescript projects:

{
   "root": true,
   "extends": [
      "@pxlwidgets/eslint-config"
   ],
   "overrides": [
      {
         "files": [
            "*.ts"
         ],
         "parserOptions": {
            "project": [
               "tsconfig.json"
            ]
         }
      }
   ]
}

IDE integration

Most modern IDE's have a way to apply code style rules from ESLint config files (either built-in or using a plug-in). When using PhpStorm, the easiest way to enable your ESLint config is by right-clicking the .eslintrc file and selecting Apply ESLint Code Style Rules. Make sure ESLint is enabled in:

File → Settings → Languages & Frameworks → JavaScript → Code Quality Tools → ESLint

Also make sure that your IDE is using your project's locally installed ESLint binary instead of a global one, to make sure that you have consistent behaviour across platforms (including Gitlab CI).

Running the linter

Simply run npx eslint <./path/to/source> to start the linter. You may want to create npm scripts in your project's package.json file to make things easier. With the scripts as in below example you can run npm run lint for a check only (suitable for pipelines) or npm run lint:fix locally to auto-fix style issues where possible.

{
    "scripts": {
        "lint": "eslint <./path/to/source>",
        "lint:fix": "eslint <./path/to/source> --fix"
    }
}

Migrating from TSLint

TSLint and ESLint can coexist, but your IDE can have trouble when code style rules for both are being applied. If you're using TSLint and want to remove it from your project, follow these steps:

• Run npm un tslint
• Delete tslint.json (On Angular projects, you want to delete this file after migrating to ESLint (see below)).

In PhpStorm, you can disable TSLint code style rules from:

File → Settings → Languages & Frameworks → TypeScript → TSLint

Development

When making changes to the configuration, always make sure to use semantic versioning to indicate breaking changes. This applies to both the .eslintrc.js file itself and any major version bumps of npm dependencies.

Releasing a new version

1. Commit all changes to the configuration, including documentation of the made changes under the Unreleased section in CHANGELOG.md.
2. Create a new header in CHANGELOG.md for the new version (Do not commit!)
3. use the npm script bump to bump the package version:

   npm run bump <new version>

   Replace with a valid semver version number, e.g. npm run bump 3.1.1. This script uses yarn under the hood to allow the header change in the changelog to be included in the version commit.

4. Publish the package (publicly) on npm:

   npm publish --access=public