Eslint-config-torchbox NPM

eslint-config-torchbox

Shareable ESLint config following Torchbox’s code style.

Usage

Install the config along with its peer dependencies:

# npm v7 and up:
npm install --save-dev eslint-config-torchbox@latest
# npm v6 and below:
npx install-peerdeps --dev eslint-config-torchbox@latest

Then configure ESLint to use this config. As a .eslintrc.js in the root of your project:

module.exports = {
  // See https://github.com/torchbox/eslint-config-torchbox for rules.
  extends: 'torchbox',
};

TypeScript

TypeScript support is currently experimental, and available separately. Make sure to install typescript v3 or v4 on your project, then:

module.exports = {
  // See https://github.com/torchbox/eslint-config-torchbox for rules.
  extends: 'torchbox/typescript',
};

The TypeScript configuration uses the same rules as the base configuration, with two exceptions:

Rules which will be checked by the TypeScript compiler anyway are disabled.
Rules which would work differently for TypeScript code have been replaced by their @typescript-eslint counterparts, where this is possible without requiring type checking as part of linting (see Design decisions).

This configuration can be used as-is even for mixed or JavaScript-only projects, but does require the typescript package to be installed.

Advanced TypeScript usage

For projects wanting stricter checks, consider using linting with type information. Here is a sample ESLint configuration:

module.exports = {
  // See https://github.com/torchbox/eslint-config-torchbox for rules.
  extends: [
    'torchbox/typescript',
    'plugin:@typescript-eslint/recommended-requiring-type-checking',
  ],
  // See https://typescript-eslint.io/docs/linting/type-linting/.
  parserOptions: {
    tsconfigRootDir: __dirname,
    project: ['./tsconfig.json'],
  },
};

Tips

Linting setup for ongoing projects

Review our CHANGELOG for guidance on how to upgrade a project’s linting to a specific version.

More generally, when retrofitting stricter linting onto an existing project, consider a gradual approach to linting strictness, so you can start using linting without having to change significant portions of the project’s code.

Common CLI flags

We recommend the following run script to add to your package.json:

"lint:js": "eslint --ext .js,.ts,.tsx --report-unused-disable-directives .",

Use the --ext flag so ESLint knows which files to lint.
Use --report-unused-disable-directives flag to ensure you do not use more eslint-disable comments than needed.
Consider using ESLint’s --cache for larger projects.

`.eslintignore`

We recommend using a .eslintignore to avoid running ESLint over large folders. Note the point of the ignore file isn’t just to determine which JS files we don’t want to be linted, but also speed up linting by excluding large folders. Here’s an example:

.git
node_modules
coverage
static_compiled
venv

`overrides`

If relevant, use ESLint’s overrides feature to make it more permissive for certain files – for example Storybook stories or unit tests, where code standards are different.

Here is an example of using overrides to disable a few specific rules for stories:

module.exports = {
  // […]
  overrides: [
    {
      files: ['*.stories.tsx'],
      rules: {
        // Don’t mandate typing for Storybook stories.
        '@typescript-eslint/explicit-module-boundary-types': 0,
        '@typescript-eslint/explicit-function-return-type': 0,
      },
    },
  ],
};

React

This config is meant first and foremost for React projects, where it will detect which rules to apply based on the version of React used on the project. The config can also be used on non-React projects – just make sure to disable the version check by adding the following in your config:

module.exports = {
  // [...]
  settings: {
    // Manually set the version to disable automated detection of the "react" dependency.
    react: { version: 'latest' },
  },
};

Vue

We do not include linting for Vue out of the box. Have a look at the eslint-plugin-vue user guide, in particular:

Choose the right predefined configuration based on the Vue version and desired level of strictness
Use the --ext flag to lint .vue files.
Make sure pre-commit hooks are configured to run ESLint on .vue files.
If using a custom parser (for example TypeScript’s), make sure to set it up alongside vue-eslint-parser as documented.

Prettier

This config is Prettier-compatible, there isn’t anything extra needed.

pre-commit

The pre-commit pre-commit hook framework doesn’t work well with ESLint. There are three major points to set up correctly:

Peer dependencies aren’t automatically installed like in other npm v7+ environment. We need to tell pre-commit what to install via its additional_dependencies configuration.
Dependency versions aren’t locked. Always pin exact versions in the configuration to have as stable of an installation as possible.
By default, the ESLint hook will only run .js files. Make sure to override its types attribute as well as files with the correct extensions (TypeScript, Vue).

Here is a sample setup with our recommended configuration:

default_language_version:
  node: system
repos:
  - repo: https://github.com/pre-commit/mirrors-eslint
    rev: v8.10.0
    hooks:
      - id: eslint
        types: [file]
        files: \.(js|ts|tsx)$
        args: [--report-unused-disable-directives]
        additional_dependencies:
          # Use the same versions as the project’s package-lock.json.
          - eslint@8.10.0
          - eslint-config-torchbox@1.0.0
          - typescript@4.6.2
          # Even on npm v7+, we need to specify all peerDependencies
          # as pre-commit installs `additional_dependencies` globally.
          - '@typescript-eslint/eslint-plugin@5.14.0'
          - '@typescript-eslint/parser@5.14.0'
          - eslint-config-airbnb@19.0.4
          - eslint-config-prettier@8.5.0
          - eslint-plugin-import@2.25.4
          - eslint-plugin-jsx-a11y@6.5.1
          - eslint-plugin-react@7.29.3
          - eslint-plugin-react-hooks@4.3.0

The latest versions to install can be resolved with either:

# Retrieve latest versions from npm:
npx install-peerdeps --dry-run --dev eslint-config-torchbox@latest
# Or retrieve currently-installed versions from the current project:
npm ls eslint eslint-config-torchbox typescript @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint-config-airbnb eslint-config-prettier eslint-plugin-import eslint-plugin-jsx-a11y eslint-plugin-react eslint-plugin-react-hooks | grep -v deduped

Experimental syntax

By default, this config uses ESLint’s built-in parser, which doesn’t support experimental ECMAScript features. If your code uses experimental syntax with Babel, make sure to set the ESLint parser to babel-eslint:

module.exports = {
  // See https://github.com/torchbox/eslint-config-torchbox for rules.
  extends: 'torchbox',
  // Support non-standard, experimental JS features that Babel knows how to process.
  parser: 'babel-eslint',
};

Design decisions

This configuration strikes a balance between ease of use for users, and ease of maintenance.

We use the same React-aware configuration everywhere, even non-React projects.
There is a single package with a single set of dependencies.

The base configuration is kept very simple, extending from the Airbnb configuration, with Prettier compatibility and more permissive rules.

TypeScript support

We use a separate TypeScript configuration file only due to its experimental nature. The TypeScript configuration does not rely on type checking, so it can also be used for JavaScript projects.

In the future, we may decide to use TypeScript for the default configuration, and have a separate configuration file for vanilla JS projects. Or document how to use the TypeScript configuration on vanilla projects (resetting the parser should be the only necessary change).

Dependencies as peerDependencies

Most of the configuration’s dependencies are specified as peerDependencies. This is necessary due to how ESLint configurations resolve their dependencies – see Support having plugins as dependencies in shareable config #3458. This will be changed in a future version of ESLint.