ESLint plugin

SWAN's ESLint package is a custom linting plugin designed to enforce the Vista Design System's evolving design language across JavaScript and TypeScript files. It helps developers write consistent and accessible SWAN-specific code by identifying deviations from SWAN’s design principles and coding conventions, thereby reducing variations.

Getting started

Prerequisites

• An ESLint setup in your project
• Peer dependencies
  • @vp/swan >= 3.18.1 < 4
  • @typescript-eslint/parser ^7 || ^8
  • eslint ^8.45.0 || ^9
  • typescript >= 4.8.4
• Node.js >= 18.18.0

Installation

CopyShare

npm i -D @vp/eslint-plugin-swan

npm i -D @vp/eslint-plugin-swan

Usage

You can integrate the plugin into your project by adding it to your ESLint config file.

Flat ESLint Config (>= ESLint v9)

CopyShare

import swanESLint from '@vp/eslint-plugin-swan'

export default [...swanESLint.configs['flat/recommended']]

import swanESLint from '@vp/eslint-plugin-swan' export default [...swanESLint.configs['flat/recommended']]

Legacy ESLint Config (< ESLint v9)

CopyShare

{
  "plugins": ["@vp/swan"],
  "extends": ["plugin:@vp/swan/recommended"]
}

{ "plugins": ["@vp/swan"], "extends": ["plugin:@vp/swan/recommended"] }

Setting individual rules

To best align with SWAN's best practices, it's advised to use the recommended configuration (shown above). However, it's possible to enable, disable, or alter the severity of individual rules if required.

Flat ESLint Config (>= ESLint v9)

CopyShare

import swanESLint from '@vp/eslint-plugin-swan'

export default [
  {
    ...swanEsLint.configs['flat/recommended'],
    rules: {
      '@vp/swan/no-deprecated-tokens': 'warn',
    },
  },
]

import swanESLint from '@vp/eslint-plugin-swan' export default [ { ...swanEsLint.configs['flat/recommended'], rules: { '@vp/swan/no-deprecated-tokens': 'warn', }, }, ]

Legacy ESLint Config (< ESLint v9)

CopyShare

{
 "plugins": ["@vp/swan"],
 "extends": ["plugin:@vp/swan/recommended"],
 "rules": {
   "@vp/swan/no-deprecated-tokens": "warn"
  }
}

{ "plugins": ["@vp/swan"], "extends": ["plugin:@vp/swan/recommended"], "rules": { "@vp/swan/no-deprecated-tokens": "warn" } }

TypeScript Projects: Type-Aware Rule Setup

Some rules in this plugin (like @vp/swan/no-deprecated) use TypeScript's type information to provide more accurate linting. These "type-aware" rules require special configuration to work properly. After setting up @vp/eslint-plugin-swan and running ESLint, if you get any parsing errors like the example below, ESLint is trying to lint files that are not a part of your typescript project i.e. files not included in your root tsconfig.json file.

Parsing error: /path/to/repo/test.tsx was not found by the project service. Consider either including it in the tsconfig.json or including it in allowDefaultProject

To fix these errors you can add the erroring file/s to the allowDefaultProject config in ESLint or you can add them to your typescript project. See below for examples for each ESLint config type.

Using allowDefaultProject

Adding files to allowDefaultProject tells ESLint to compile these files with the default project compiler options which means you don't need to update your typescript project to include these files. For more information on projectService see the typescript-eslint docs.

Notes:

• allowDefaultProject doesn't allow ** in the path to prevent overuse
• Files in allowDefaultProject may not also be included in their nearest tsconfig.json

Flat ESLint Config eslint.config.js

CopyShare

export default [
  ...swanESLint.configs['flat/recommended'],
  {
    languageOptions: {
      parserOptions: {
        // Use `EXPERIMENTAL_useProjectService` if using `@typescript-eslint/parser` v7
        EXPERIMENTAL_useProjectService: {
          allowDefaultProject: ['test.tsx'],
        },
        // Use `projectService` if using `@typescript-eslint/parser` v8
        projectService: {
          allowDefaultProject: ['test.tsx'],
        },
      },
    },
  },
]

export default [ ...swanESLint.configs['flat/recommended'], { languageOptions: { parserOptions: { // Use `EXPERIMENTAL_useProjectService` if using `@typescript-eslint/parser` v7 EXPERIMENTAL_useProjectService: { allowDefaultProject: ['test.tsx'], }, // Use `projectService` if using `@typescript-eslint/parser` v8 projectService: { allowDefaultProject: ['test.tsx'], }, }, }, }, ]

Legacy ESLint Config .eslintrc.js

CopyShare

{
  "plugins": ["@vp/swan"],
  "extends": ["plugin:@vp/swan/recommended"],
  "parserOptions": {
    // Use `EXPERIMENTAL_useProjectService` if using `@typescript-eslint/parser` v7
    "EXPERIMENTAL_useProjectService": {
      "allowDefaultProject": ["test.tsx"]
    },
    // Use `projectService` if using `@typescript-eslint/parser` v8
    "projectService": {
      "allowDefaultProject": ["test.tsx"]
    }
  }
}

{ "plugins": ["@vp/swan"], "extends": ["plugin:@vp/swan/recommended"], "parserOptions": { // Use `EXPERIMENTAL_useProjectService` if using `@typescript-eslint/parser` v7 "EXPERIMENTAL_useProjectService": { "allowDefaultProject": ["test.tsx"] }, // Use `projectService` if using `@typescript-eslint/parser` v8 "projectService": { "allowDefaultProject": ["test.tsx"] } } }

Updating your typescript project in tsconfig.json

You can also add the erroring files to your typescript project. To do that, add each file or directory that isn't already included to your tsconfig.json under the include parameter. If you are linting js files you also need to set allowJs: true so that they are included in your typescript project. E.g:

CopyShare

{
  // Your other config here
  "compilerOptions": {
    "allowJs": true
  },
  "include": ["existing/paths/and/files.ext", "test.tsx"]
}

{ // Your other config here "compilerOptions": { "allowJs": true }, "include": ["existing/paths/and/files.ext", "test.tsx"] }

If desired, you can separate out your typescript config for ESLint by creating a separate tsconfig.eslint.json file. Note you need to set the defaultProject parameter of projectService or EXPERIMENTAL_useProjectService to point to this file instead if you decide to do this. More info on that here.

tsconfig.eslint.jsoneslint.config.js

CopyShare

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "allowJs": true
  },
  "include": ["existing/paths/and/files.ext", "test.tsx"]
}

{ "extends": "./tsconfig.json", "compilerOptions": { "allowJs": true }, "include": ["existing/paths/and/files.ext", "test.tsx"] }

CopyShare

export default [
  ...swanESLint.configs['flat/recommended'],
  {
    languageOptions: {
      parserOptions: {
        // Use `EXPERIMENTAL_useProjectService` if using `@typescript-eslint/parser` v7
        EXPERIMENTAL_useProjectService: {
          defaultProject: 'tsconfig.eslint.json',
        },
        // Use `projectService` if using `@typescript-eslint/parser` v8
        projectService: {
          defaultProject: 'tsconfig.eslint.json',
        },
      },
    },
  },
]

export default [ ...swanESLint.configs['flat/recommended'], { languageOptions: { parserOptions: { // Use `EXPERIMENTAL_useProjectService` if using `@typescript-eslint/parser` v7 EXPERIMENTAL_useProjectService: { defaultProject: 'tsconfig.eslint.json', }, // Use `projectService` if using `@typescript-eslint/parser` v8 projectService: { defaultProject: 'tsconfig.eslint.json', }, }, }, }, ]

Rules included

Each rule has its own README with usage, rationale, and examples.

Troubleshooting/FAQs

Changelog

See the complete Changelog