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

You will need to have ESLint setup done for your project. Refer to Getting Started with ESLint if you don't have a setup.

Peer dependencies

This plugin requires the following peer dependencies to be installed in your project:

"peerDependencies": {
  "@vp/swan": ">= 3.18.1 < 4",
  "@typescript-eslint/parser": "^7 || ^8",
  "eslint": "^8.45.0 || ^9",
  "typescript": ">= 4.8.4"
}

"peerDependencies": {
  "@vp/swan": ">= 3.18.1 < 4",
  "@typescript-eslint/parser": "^7 || ^8",
  "eslint": "^8.45.0 || ^9",
  "typescript": ">= 4.8.4"
}

Note that the minimum required version for SWAN is 3.18.1, as some configurations are shared only from SWAN 3.18.1 and onwards to this plugin.

Environment support

We recommend a minimum Node.js version of "18.18.0" for a predictable, stable experience. It is also in accordance with ESLint setup requirements. Versions below may/may not work.

"engines": {
  "node": ">= 18.18.0"
}

"engines": {
  "node": ">= 18.18.0"
}

Installation

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

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

Usage

This plugin provides a recommended ESLint configuration preloaded with SWAN-specific rules. You can integrate it into your project using either the flat config format (ESLint v9+) or the legacy .eslintrc format (< ESLint v9).

Flat ESLint Config (>= ESLint v9)

If you're using the flat config format, extend the recommended setup like this:

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

export default [
  ...swanESLint.configs['flat/recommended'],
  // your existing config
]

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

export default [
  ...swanESLint.configs['flat/recommended'],
  // your existing config
]

Legacy ESLint Config (< ESLint v9)

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

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

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.

How to Configure

Create a dedicated tsconfig.eslint.json in your project root:

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

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

And then update your ESLint config to use it:

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

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

Rules

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

Rule ID	Description	Default Severity	Docs with examples	Suggestion available
`@vp/swan/enforce-grid-structure`	Enforces consistent grid structure across layouts.	`error`	README	-
`@vp/swan/no-internal-tokens`	Disallows use of internal SWAN tokens like `SwanInternal`, `SwanComp`.	`error`	README	No
`@vp/swan/no-internal-components`	Disallows usage of internal-only SWAN components.	`error`	README	No
`@vp/swan/no-deprecated-tokens`	Flags deprecated tokens from the design system.	`error`	README	Partially
`@vp/swan/no-deprecated`	Flags deprecated code patterns/components.	`error`	README	Partially
`@vp/swan/required-accessibility-props`	Ensures accessibility-related props (like `aria-*`) are used where needed.	`error`	README	Yes
`@vp/swan/enforce-font-skin`	Enforce usage of `fontSkin` prop for consistent font styling	`warn`	README	Partially
`@vp/swan/no-mixed-font-props`	Disallows mixing fontSkin with individual typography props like `fontSize`, `fontWeight`, or `fontFamily`.	`error`	README	-
`@vp/swan/no-classname`	Disallow the use of SWAN classes (such as `swan-*` class) on either any components or elements.	`error`	README	-

Overriding a rule

You can override individual rule severities even when using the recommended config.

The default severity levels for rules are selected to align with SWAN's best practices. If you need to modify these severities, please consult with the Design Systems team to ensure consistency and maintainability across projects.

Flat Config Example

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

export default [
  {
    rules: {
      '@vp/swan/[rule-id]': 'warn', // overriding severity
    },
  },
]

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

export default [
  {
    rules: {
      '@vp/swan/[rule-id]': 'warn', // overriding severity
    },
  },
]

Legacy .eslintrc Example

{
 "plugins": ["@vp/swan"],
 "extends": ["plugin:@vp/swan/recommended"],
 "rules": {
   "@vp/swan/[rule-id]": "warn" // overriding severity
  }
}

{
 "plugins": ["@vp/swan"],
 "extends": ["plugin:@vp/swan/recommended"],
 "rules": {
   "@vp/swan/[rule-id]": "warn" // overriding severity
  }
}

FAQs

Update your ESLint version to 8.45 or above.