Install and Configure the Vega ESLint Plugin

The Vega ESLint plugin, eslint-plugin-kepler, provides automated linting rules for Vega apps, helping you discover and fix performance, compatibility, and accessibility issues.

Prerequisites

Install the plugin and its dependencies:

npm install --save-dev @amazon-devices/eslint-plugin-kepler jsonc-eslint-parser

Configure the plugin

Update extends, plugins, and overrides sections of your .eslintrc configuration file:

{
   "extends": [
      "@react-native",
      "eslint:recommended",
      "plugin:@amazon-devices/eslint-plugin-kepler/kepler" // add the extension
   ],
   "plugins": [
      "@typescript-eslint",
      "@amazon-devices/eslint-plugin-kepler" //include the plugin
   ],
   "overrides": [
      {
         "files": ["**/*.ts", "**/*.tsx"],
         "parser": "@typescript-eslint/parser",
         "parserOptions": {
            "project": "./tsconfig.json"
         }
      },
      {
         "files": ["package.json"],
         "parser": "jsonc-eslint-parser" // this parser is needed to check the package.json
      }
   ]
}

The kepler configuration includes all Vega rules. To use a subset of rules, extend one or more of these configurations instead:

performance - Performance-related rules only
system-distributed-libs - System distributed library checks only (package.json validation and import informational flagging)
accessibility - Accessibility rules only

For example, to use only the performance and system distributed library rules:

module.exports = {
   plugins: ["@amazon-devices/eslint-plugin-kepler"],
   extends: [
      "plugin:@amazon-devices/eslint-plugin-kepler/performance",
      "plugin:@amazon-devices/eslint-plugin-kepler/system-distributed-libs"
   ],
}

To use only the accessibility rules:

module.exports = {
   plugins: ["@amazon-devices/eslint-plugin-kepler"],
   extends: ["plugin:@amazon-devices/eslint-plugin-kepler/accessibility"],
}

Save the file. ESLint now loads the Vega rules the next time you run the linter.

(Optional) To customize lint rules, follow ESLint’s configure rules guide. If you skip this step, all rules run at their default severities. For rules provided by the Vega ESLint plugin, see Understand the performance rules, Understand the system distributed library rules, and Understand the accessibility rules.

Specify the custom formatter in the lint script of your package.json file:

{
   "scripts": {
      "lint": "eslint src test package.json --ext .ts,.tsx --format node_modules/@amazon-devices/eslint-plugin-kepler/dist/formatters/default.js"
   }
}

Your lint script now uses the Vega custom formatter.

Run the linter:
npm run lint
If package.json warnings don’t appear, confirm jsonc-eslint-parser is installed and that package.json is passed to the eslint command. You can see the result on the console: The linter also generates an HTML report: You can check these linter warnings on VS Code while hovering over your code:

Understand the performance rules

The following rules help identify common performance issues in Vega apps and enforce best practices for optimal runtime performance. In the rule tables on this page, an Error rule flags issues and fails the build. A Warn rule flags issues but doesn’t fail the build.

Rule Name	Default severity	Description	Best Practice
@amazon-devices/kepler/flat-list	Warn	Checks if the FlatList element has enough properties	FlatList
@amazon-devices/kepler/check-subscription	Warn	Checks if callbacks installed by useAddVegaAppStateListenerCallback and useAddUserInputListenerCallback are properly unsubscribed	Listeners, event subscriptions, and timers
@amazon-devices/kepler/animated	Error	Checks if Animated element component uses a native driver	The Animated library
@amazon-devices/kepler/detect-report-fully-drawn	Warn	Checks if the code invokes useReportFullyDrawn() properly	Fully drawn marker
@amazon-devices/kepler/detect-splash-screen	Warn	Checks if the code invokes usePreventHideSplashScreen() and useHideSplashScreenCallback() properly.	SplashScreenManager for React Native 0.83 or React Native 0.72

Understand the system distributed library rules

The following rules detect system distributed library usage and guide you on proper implementation.

Rule Name	Default severity	Description
@amazon-devices/kepler/sdl-package-version-check	Error	Validates that system distributed library dependencies in `package.json` use proper semantic versioning.
@amazon-devices/kepler/sdl-package-version-check-imports	Warn	Flags system distributed library imports to remind you they work differently than standard React Native libraries.

(Optional) configure semantic version guidance

The system distributed library rules check semantic versioning in your package.json dependencies. By default, the plugin uses auto mode to detect your project’s versioning settings. Override the default by setting the semverGuidance option:

Patch only mode (semverGuidance: "patch"): Restricts updates to patches using ~ prefix.
Minor and patch mode (semverGuidance: "minor"): Allows minor updates using ^ prefix.
Auto mode (semverGuidance: "auto"): Detects settings based on project signatures in the project repo. This is the default.

Example configuration using patch-only mode:

module.exports = {
  plugins: ["@amazon-devices/eslint-plugin-kepler"],
  rules: {
    "@amazon-devices/kepler/sdl-package-version-check": [
      "error",
      { semverGuidance: "patch" },
    ], // auto is the default
    "@amazon-devices/kepler/sdl-package-version-check-imports": [
      "warn",
      { semverGuidance: "patch" },
    ],
  },
};

Understand the accessibility rules

The following rules flag components that assistive technologies, such as screen readers, can’t describe or operate correctly. For guidance on the accessibility props these rules check, see Accessibility for React Native 0.83 or React Native 0.72.

Rule Name	Default severity	Description
@amazon-devices/kepler/missing-accessible-label	Error	Flags interactive or informative elements that don’t have an accessible label, such as `aria-label`.
@amazon-devices/kepler/missing-accessibility-state	Error	Flags checkboxes, switches, radio buttons, and tabs that don’t expose their checked or selected state.
@amazon-devices/kepler/invalid-role-value	Error	Flags `role` or `accessibilityRole` values that aren’t valid.
@amazon-devices/kepler/dangling-described-by-ref	Error	Flags `accessibilityDescribedBy` references to a `nativeID` that doesn’t exist.
@amazon-devices/kepler/dangling-transport-control-ref	Error	Flags `transportControls` entries that reference a `nativeID` that doesn’t exist.
@amazon-devices/kepler/deprecated-prop-rename	Warn	Flags deprecated accessibility props that have a replacement, such as `accessibilityLabel` (use `aria-label`) and `accessibilityRole` (use `role`).
@amazon-devices/kepler/missing-accessibility-role	Warn	Flags interactive elements that don’t have a `role`.
@amazon-devices/kepler/missing-accessibility-hint	Warn	Flags interactive elements that don’t have an `accessibilityHint`.

To change the severity of an accessibility rule, override it in the rules section of your ESLint configuration:

module.exports = {
  rules: {
    "@amazon-devices/kepler/missing-accessible-label": "warn", // default: error
    "@amazon-devices/kepler/missing-accessibility-hint": "error", // default: warn
    "@amazon-devices/kepler/missing-accessibility-role": "off", // default: warn
  },
};

To suppress a rule for a single element, add a standard ESLint suppression comment on the line before it:

{/* eslint-disable-next-line @amazon-devices/kepler/missing-accessible-label */}
<Image source={icon} />

To find and fix these issues as you edit, use the A11y Inspector in Vega Studio. It uses the same rules and recognizes the same suppression comments.

(Optional) configure VS Code for JSON validation

If you want to see errors and warnings in VS Code’s package.json, add json to these settings.json entries:

"eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    // add the line below
    "json"
  ],
  "eslint.probe": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    // add the line below
    "json"
  ],

​Prerequisites

​Configure the plugin

​Understand the performance rules

​Understand the system distributed library rules

​(Optional) configure semantic version guidance

​Understand the accessibility rules

​(Optional) configure VS Code for JSON validation

​Related topics