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.

When You Need This Setup

When your main tsconfig.json only covers certain directories (like src/), but ESLint needs to lint files outside those folders—such as tests, configuration files, or scripts. You may also need this setup if you encounter errors about missing type information during linting. Refer to the Typed Linting FAQ.

How to Configure

To enable type-aware linting, create a dedicated `tsconfig.eslint.json` at your project root. This ensures ESLint can access type information for all relevant files, including tests and config scripts.

1. Create tsconfig.eslint.json:

CopyShare

{
  "extends": "./tsconfig.json",
  "include": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", ".eslintrc.js"]
}

{ "extends": "./tsconfig.json", "include": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", ".eslintrc.js"] }

2. Update your Flat ESLint Config:

Add the parserOptions.project field to point to your config:

CopyShare

export default [
  {
    languageOptions: {
      parserOptions: {
        project: './tsconfig.eslint.json',
      },
    },
  },
]

export default [ { languageOptions: { parserOptions: { project: './tsconfig.eslint.json', }, }, }, ]

3. Update your Legacy ESLint Config (`.eslintrc`):

Set the parserOptions.project field:

CopyShare

{
  "parserOptions": {
    "project": "./tsconfig.eslint.json"
  }
}

{ "parserOptions": { "project": "./tsconfig.eslint.json" } }

Rules included

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

Troubleshooting/FAQs

Changelog

See the complete Changelog