@volvo-cars/eslint-config

@volvo-cars/eslint-config

Questions? Ask in Slack #vcc-ui

ESlint configuration for TypeScript and JavaScript projects at Volvo Cars.

Helps you fix common issues and maintain best practices. Code formatting should be done using Prettier with the default settings and is not handled with ESlint.

Types of rules

• :no_entry_sign: error - rules that prevent problems that risk causing bugs or performance issues in production.
• :warning: warn - stylistic rules that make code more readable, consistent and maintainable, or rules only targeting tests or documentation.

Prevent warnings from being merged to the main branch with the --max-warnings 0 command line flag. Warnings are OK to disable with eslint-disable if there is good reason.

Lint errors should not be disabled with inline comments, except as a temporary measure after enabling new stricter rules.

Install (flat config)

All configurations in this package have dependencies as peer dependencies expecting you to install them in your project.

yarn add -D @volvo-cars/eslint-config eslint-plugin-import typescript-eslint

Scripts

Recommended scripts for your package.json.

Run eslint, failure should prevent merge to master/main.

  "lint": "eslint --max-warnings 0 .",

Run eslint to check for ignored rules with severity error. Should be discouraged but not necessarily prevented.

  "lint:ignored-errors": "eslint --report-unused-disable-directives --no-inline-config --quiet .",

Extensions are no longer set with the --ext flag. Instead add a files array to the eslint configuration:

{
  files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx', '**/*.mjs'];
}

Configuration

Create a eslint.config.js file in the root of your project.

All projects

yarn add -D eslint-plugin-import typescript-eslint

These rules are not very opinionated and should be used for all JavaScript projects at Volvo Cars.

Includes eslint:recommended rules, confusing browser globals and a few rules to enforce using modern language features.

import volvoCarsEslintConfig from '@volvo-cars/eslint-config/flat/index.mjs';

export default [
  ...volvoCarsEslintConfig,
  {
    ignores: ['!.github', 'node_modules/', 'coverage/', '.yarn/'],
  },
];

If you don't use ESM, you can use the CommonJS syntax:

const volvoCarsEslintConfig = require('@volvo-cars/eslint-config/flat/index.js');

module.exports = [
  ...volvoCarsEslintConfig,
  {
    ignores: ['!.github', 'node_modules/', 'coverage/', '.yarn/'],
  },
];

With React

yarn add -D eslint-plugin-import eslint-plugin-react eslint-plugin-react-hooks @typescript-eslint/parser @typescript-eslint/eslint-plugin

Adds most recommended rules from eslint-plugin-react and eslint-plugin-react-hooks.

 import volvoCarsEslintConfig from '@volvo-cars/eslint-config/flat/index.mjs';
+import volvoCarsReactEslintConfig from '@volvo-cars/eslint-config/flat/react.mjs';

 export default [
   ...volvoCarsEslintConfig,
+  ...volvoCarsReactEslintConfig,
   {
     ignores: ['!.github', 'node_modules/', 'coverage/', '.yarn/'],
   },

Import sorting

@volvo-cars/eslint-config/import-sort includes eslint-plugin-import rules for consistent placement and sorting of import statements. Keeping the list of imports sorted and formatted in an automatic, deterministic way reduces potential merge conflicts and the cognitive load of managing imports. With Visual Studio Code features such as editor.foldingImportsByDefault and Auto Imports, import statements is something you rarely need to deal with manually.

 import volvoCarsEslintConfig from '@volvo-cars/eslint-config/flat/index.mjs';
 import volvoCarsReactEslintConfig from '@volvo-cars/eslint-config/flat/react.mjs';
+import volvoCarsImportSortEslintConfig from '@volvo-cars/eslint-config/flat/import-sort.mjs';

 export default [
   ...volvoCarsEslintConfig,
   ...volvoCarsReactEslintConfig,
+  ...volvoCarsImportSortEslintConfig,
   {
     ignores: ['!.github', 'node_modules/', 'coverage/', '.yarn/'],
   },

Jest and Testing Library

yarn add -D eslint-plugin-jest eslint-plugin-testing-library

If your project is using the Jest test runner or the Testing Library. Adds eslint-plugin-jest and eslint-plugin-testing-library with some rules for files matching typical test file patterns.

 import volvoCarsEslintConfig from '@volvo-cars/eslint-config/flat/index.mjs';
 import volvoCarsReactEslintConfig from '@volvo-cars/eslint-config/flat/react.mjs';
 import volvoCarsImportSortEslintConfig from '@volvo-cars/eslint-config/flat/import-sort.mjs';
+import volvoCarsJestEslintConfig from '@volvo-cars/eslint-config/flat/jest.mjs';
+import volvoCarsTestingLibraryEslintConfig from '@volvo-cars/eslint-config/flat/testing-library.mjs';

 export default [
   ...volvoCarsEslintConfig,
   ...volvoCarsReactEslintConfig,
   volvoCarsImportSortEslintConfig,
+  ...volvoCarsJestEslintConfig,
+  ...volvoCarsTestingLibraryEslintConfig,
   {
     ignores: ['!.github', 'node_modules/', 'coverage/', '.yarn/'],
   },

Vitest

yarn add -D eslint-plugin-vitest

If your project is using the Vitest test runner, adds eslint-plugin-vitest with some rules for files matching typical test file patterns, like the setup for Jest above. It's also compatible with @volvo-cars/eslint-config/testing-library.

 import volvoCarsEslintConfig from '@volvo-cars/eslint-config/flat/index.mjs';
 import volvoCarsReactEslintConfig from '@volvo-cars/eslint-config/flat/react.mjs';
 import volvoCarsImportSortEslintConfig from '@volvo-cars/eslint-config/flat/import-sort.mjs';
-import volvoCarsJestEslintConfig from '@volvo-cars/eslint-config/flat/jest.mjs';
+import volvoCarsVitestEslintConfig from '@volvo-cars/eslint-config/flat/vitest.mjs';
 import volvoCarsTestingLibraryEslintConfig from '@volvo-cars/eslint-config/flat/testing-library.mjs';

 export default [
   ...volvoCarsEslintConfig,
   ...volvoCarsReactEslintConfig,
   volvoCarsImportSortEslintConfig,
-  ...volvoCarsJestEslintConfig,
+  ...volvoCarsVitestEslintConfig,
   ...volvoCarsTestingLibraryEslintConfig,
   {
     ignores: ['!.github', 'node_modules/', 'coverage/', '.yarn/'],

Storybook

If your project is using Storybook.

yarn add -D eslint-plugin-storybook

 import volvoCarsEslintConfig from '@volvo-cars/eslint-config/flat/index.mjs';
 import volvoCarsReactEslintConfig from '@volvo-cars/eslint-config/flat/react.mjs';
 import volvoCarsImportSortEslintConfig from '@volvo-cars/eslint-config/flat/import-sort.mjs';
 import volvoCarsVitestEslintConfig from '@volvo-cars/eslint-config/flat/vitest.mjs';
 import volvoCarsTestingLibraryEslintConfig from '@volvo-cars/eslint-config/flat/testing-library.mjs';
+import volvoCarsStorybookEslintConfig from '@volvo-cars/eslint-config/flat/storybook.mjs';

 export default [
   ...volvoCarsEslintConfig,
   ...volvoCarsReactEslintConfig,
   volvoCarsImportSortEslintConfig,
   ...volvoCarsVitestEslintConfig,
   ...volvoCarsTestingLibraryEslintConfig,
+  ...volvoCarsStorybookEslintConfig,
   {
     ignores: ['!.github', 'node_modules/', 'coverage/', '.yarn/'],

With Next.js

Includes the Next.js eslint plugin.

yarn add -D @next/eslint-plugin-next

 import volvoCarsEslintConfig from '@volvo-cars/eslint-config/flat/index.mjs';
 import volvoCarsReactEslintConfig from '@volvo-cars/eslint-config/flat/react.mjs';
 import volvoCarsImportSortEslintConfig from '@volvo-cars/eslint-config/flat/import-sort.mjs';
 import volvoCarsVitestEslintConfig from '@volvo-cars/eslint-config/flat/vitest.mjs';
 import volvoCarsTestingLibraryEslintConfig from '@volvo-cars/eslint-config/flat/testing-library.mjs';
 import volvoCarsStorybookEslintConfig from '@volvo-cars/eslint-config/flat/storybook.mjs';
+import volvoCarsNextEslintConfig from '@volvo-cars/eslint-config/flat/next.mjs';

 export default [
   ...volvoCarsEslintConfig,
   ...volvoCarsReactEslintConfig,
   volvoCarsImportSortEslintConfig,
   ...volvoCarsVitestEslintConfig,
   ...volvoCarsTestingLibraryEslintConfig,
   ...volvoCarsStorybookEslintConfig,
+  ...volvoCarsNextEslintConfig,
   {
     ignores: ['!.github', 'node_modules/', 'coverage/', '.yarn/'],

Monorepos

 import volvoCarsEslintConfig from '@volvo-cars/eslint-config/flat/index.mjs';
 import volvoCarsReactEslintConfig from '@volvo-cars/eslint-config/flat/react.mjs';
 import volvoCarsImportSortEslintConfig from '@volvo-cars/eslint-config/flat/import-sort.mjs';
 import volvoCarsVitestEslintConfig from '@volvo-cars/eslint-config/flat/vitest.mjs';
 import volvoCarsTestingLibraryEslintConfig from '@volvo-cars/eslint-config/flat/testing-library.mjs';
 import volvoCarsStorybookEslintConfig from '@volvo-cars/eslint-config/flat/storybook.mjs';
 import volvoCarsNextEslintConfig from '@volvo-cars/eslint-config/flat/next.mjs';
+import volvoCarsMonorepoEslintConfig from '@volvo-cars/eslint-config/flat/monorepo.mjs';

 export default [
   ...volvoCarsEslintConfig,
   ...volvoCarsReactEslintConfig,
   volvoCarsImportSortEslintConfig,
   ...volvoCarsVitestEslintConfig,
   ...volvoCarsTestingLibraryEslintConfig,
   ...volvoCarsStorybookEslintConfig,
   ...volvoCarsNextEslintConfig,
+  ...volvoCarsMonorepoEslintConfig,
   {
     ignores: ['!.github', 'node_modules/', 'coverage/', '.yarn/'],

Gradually enabling stricter rules with supress-eslint-errors

Updating @volvo-cars/eslint-config to a newer version or enabling your own stricter rules can be a challenge in a large code base where you don't want to change a lot of code at once. ESLint provides autofixers for a lot of issues, but generally not if the code change is deemed potentially unsafe. For this reason @volvo-cars/eslint-config includes an additional script that adds eslint-disable rules to the files with any remaining issues. Example:

// TODO: Fix eslint issues the next time this file is edited.
/* eslint-disable no-sparse-arrays, react/display-name */

Recommended actions for a configuration change:

1. Update the ESLint configuration or packages
2. Run yarn run eslint --fix
3. Run yarn run supress-eslint-errors .
4. Enable PR annotations in CI.

Another option is to temporarily disable rules in your configuration, but only for the specific files or folders where you still have errors. These changes risk being more permanent though, because you don't have the PR annotations reminding you. In eslint.config.js.

//Rules temporarily disabled after updating the eslint config.
// Remove an pattern from here to enable all rules again.
{
  files: ['src/some-old-feature-were-not-touching/**'],
  rules: {
    'no-unused-vars': 'off',
  }
}

CI checks

Recommended GitHub Action steps for pull requests. Will fail for lint warnings or errors, and produce GitHub PR annotations for ignored lint errors.

      - name: Lint
        run: |
          yarn run eslint \
            --max-warnings 0 \
            .

      - name: Get changed files
        id: changes
        if: ${{ github.event_name == 'pull_request' }}
        run: |
          git fetch --no-tags --depth=200 origin master
          # Put file names in a single-line string. Actions output doesn't support multi-line strings.
          echo "::set-output name=changed-files::$(git diff --name-only --diff-filter=ACMR origin/master... | tr '\n' '|' | sed 's| |\\ |g')"

      - name: Pull request annotations for disabled eslint errors
        if: ${{ github.event_name == 'pull_request' }}
        continue-on-error: true
        run: |
          echo "${{ steps.changes.outputs.changed-files }}" | tr '|' '\n' | grep -E '\.(tsx|ts|js|jsx)$' \
            | xargs yarn run eslint \
              --quiet \
              --report-unused-disable-directives \
              --no-inline-config \
              --no-error-on-unmatched-pattern \

Install (legacy .eslintrc)

Flat config is the default with ESLint 9.0.0 and later. But if you still want to use the legacy configuration, you’ll need to set the ESLINT_USE_FLAT_CONFIG environment variable to false.

All configurations in this package have dependencies as peer dependencies expecting you to install them in your project.

yarn add -D @volvo-cars/eslint-config eslint-plugin-import @typescript-eslint/eslint-plugin @typescript-eslint/parser

Scripts (legacy .eslintrc)

Recommended scripts for your package.json.

Run eslint, failure should prevent merge to master/main.

  "lint": "eslint --max-warnings 0 --ext .js,.jsx,.ts,.tsx .",

Run eslint to check for ignored rules with severity error. Should be discouraged but not necessarily prevented.

  "lint:ignored-errors": "eslint --report-unused-disable-directives --no-inline-config --quiet --ext .js,.jsx,.ts,.tsx .",

Configuration (legacy .eslintrc)

Create a .eslintrc.yaml file in the root of your project.

All projects (legacy .eslintrc)

These rules are not very opinonated and should be used for all JavaScript projects at Volvo Cars.

Includes eslint:recommended rules, confusing browser globals and a few rules to enforce using modern language features.

extends:
  - '@volvo-cars/eslint-config'

With React (legacy .eslintrc)

Adds most recommended rules from eslint-plugin-react and eslint-plugin-react-hooks.

extends:
  - '@volvo-cars/eslint-config'
+ - '@volvo-cars/eslint-config/react'

Import sorting (legacy .eslintrc)

@volvo-cars/eslint-config/import-sort includes eslint-plugin-import rules for consistent placement and sorting of import statements. Keeping the list of imports sorted and formatted in an automatic, deterministic way reduces potential merge conflicts and the cognitive load of managing imports. With Visual Studio Code features such as editor.foldingImportsByDefault and Auto Imports, import statements is something you rarely need to deal with manually.

extends:
  - '@volvo-cars/eslint-config'
  - '@volvo-cars/eslint-config/react'
+ - '@volvo-cars/eslint-config/import-sort'

Jest and Testing Library (legacy .eslintrc)

If your project is using the Jest test runner or the Testing Library. Adds eslint-plugin-jest and eslint-plugin-testing-library with some rules for files matching typical test file patterns.

extends:
  - '@volvo-cars/eslint-config'
  - '@volvo-cars/eslint-config/react'
  - '@volvo-cars/eslint-config/import-sort'
+ - '@volvo-cars/eslint-config/jest'
+ - '@volvo-cars/eslint-config/testing-library'

Vitest (legacy .eslintrc)

If your project is using the Vitest test runner, adds eslint-plugin-vitest with some rules for files matching typical test file patterns, like the setup for Jest above. It's also compatible with @volvo-cars/eslint-config/testing-library.

extends:
  - '@volvo-cars/eslint-config'
  - '@volvo-cars/eslint-config/react'
  - '@volvo-cars/eslint-config/import-sort'
+ - '@volvo-cars/eslint-config/vitest'

Storybook (legacy .eslintrc)

If your project is using Storybook.

extends:
  - '@volvo-cars/eslint-config'
  - '@volvo-cars/eslint-config/react'
  - '@volvo-cars/eslint-config/import-sort'
  - '@volvo-cars/eslint-config/jest'
  - '@volvo-cars/eslint-config/testing-library'
+ - '@volvo-cars/eslint-config/storybook'

With Next.js (legacy .eslintrc)

Includes the Next.js eslint plugin.

extends:
  - '@volvo-cars/eslint-config'
  - '@volvo-cars/eslint-config/react'
  - '@volvo-cars/eslint-config/import-sort'
  - '@volvo-cars/eslint-config/jest'
  - '@volvo-cars/eslint-config/testing-library'
  - '@volvo-cars/eslint-config/storybook'
+ - '@volvo-cars/eslint-config/next'

Monorepos (legacy .eslintrc)

Add a single version of @volvo-cars/eslint-config in the root workspace, and a .eslintrc.yaml file in the root of the repo:

root: true
extends:
  - '@volvo-cars/eslint-config'
  - '@volvo-cars/eslint-config/monorepo'
  - '@volvo-cars/eslint-config/react'
  - '@volvo-cars/eslint-config/import-sort'
  - '@volvo-cars/eslint-config/jest'

Add separate .eslintrc.yaml files to each application folder, e.g. for a Next.js application:

extends:
  - '@volvo-cars/eslint-config/next'

Gradually enabling stricter rules with supress-eslint-errors

Updating @volvo-cars/eslint-config to a newer version or enabling your own stricter rules can be a challenge in a large code base where you don't want to change a lot of code at once. ESLint provides autofixers for a lot of issues, but generally not if the code change is deemed potentially unsafe. For this reason @volvo-cars/eslint-config includes an additional script that adds eslint-disable rules to the files with any remaining issues. Example:

// TODO: Fix eslint issues the next time this file is edited.
/* eslint-disable no-sparse-arrays, react/display-name */

Recommended actions for a configuration change:

1. Update the ESLint configuration or packages
2. Run yarn run eslint --ext .js,.jsx,.ts,.tsx --fix
3. Run yarn run supress-eslint-errors .
4. Enable PR annotations in CI.

Another option is to temporarily disable rules in your configuration, but only for the specific files or folders where you still have errors. These changes risk being more permanent though, because you don't have the PR annotations reminding you. In .eslintrc.yaml.

overrides:
  - files:
      # Rules temporarily disabled after updating the eslint config.
      # Remove an pattern from here to enable all rules again.
      - 'src/some-old-feature-were-not-touching/**'
    rules:
      'no-unused-vars': 'off'

CI checks

Recommended GitHub Action steps for pull requests. Will fail for lint warnings or errors, and produce GitHub PR annotations for ignored lint errors.

      - name: Lint
        run: |
          yarn run eslint \
            --ext .js,.jsx,.ts,.tsx \
            --max-warnings 0 \
            .

      - name: Get changed files
        id: changes
        if: ${{ github.event_name == 'pull_request' }}
        run: |
          git fetch --no-tags --depth=200 origin master
          # Put file names in a single-line string. Actions output doesn't support multi-line strings.
          echo "::set-output name=changed-files::$(git diff --name-only --diff-filter=ACMR origin/master... | tr '\n' '|' | sed 's| |\\ |g')"

      - name: Pull request annotations for disabled eslint errors
        if: ${{ github.event_name == 'pull_request' }}
        continue-on-error: true
        run: |
          echo "${{ steps.changes.outputs.changed-files }}" | tr '|' '\n' | grep -E '\.(tsx|ts|js|jsx)$' \
            | xargs yarn run eslint \
              --quiet \
              --report-unused-disable-directives \
              --no-inline-config \
              --no-error-on-unmatched-pattern \
              --ext .js,.jsx,.ts,.tsx