eslint-plugin-kepler

An ESLint Plugin to suggest Vega App Development best practices.

Install

1. Add this package to devDependencies section of package.json:

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

2. For package.json validation (System Distributed Library rules), you must install the ESLint JSON parser:

npm install --save-dev jsonc-eslint-parser

You must also add the package.json to the lint command line in your package.json scripts as shown below.

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

Set up

To use Vega ESLint Plugin, complete the below steps in your Vega App Project.

1. Configure Vega rules in the App's eslint config

   eslint-plugin-kepler provides default configs that can be directly imported in App projects. To do so, add the following configuration in Vega App's ESLint config file .eslintrc.js.

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

   Available configs:

   • kepler - All Vega rules (performance + system distributed library checks + API privileges + backward compatibility)
   • performance - Performance-related rules only
   • system-distributed-libs - System distributed library checks (package.json validation and import informational flagging)
   • api-privileges - API privileges validation rules
   • backward-compatibility - Backward compatibility validation rules for Vega library projects

   You can use multiple configs:

   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",
           "plugin:@amazon-devices/eslint-plugin-kepler/api-privileges",
           "plugin:@amazon-devices/eslint-plugin-kepler/backward-compatibility"
       ],
   }

   Or use the comprehensive config:

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

   You can also override severity of specific rules:

   module.exports = {
       plugins: ["@amazon-devices/eslint-plugin-kepler"],
       extends: ["plugin:@amazon-devices/eslint-plugin-kepler/kepler"],
       rules: {
           "@amazon-devices/kepler/flat-list": "error",
           "@amazon-devices/kepler/sdl-package-version-check": "warn",
           "@amazon-devices/kepler/sdl-package-version-check-imports": "off",
           "@amazon-devices/kepler/api-privileges-check": "error",
           "@amazon-devices/kepler/api-privilege-state-check": "error",
           "@amazon-devices/kepler/backward-compatibility": "error",
           "@amazon-devices/kepler/backward-compatibility-copy-on-pack": "error",
           "@amazon-devices/kepler/package-migration": "error"
       }
   }

   System Distributed Library Rules Configuration

   The system distributed library rules support a semverGuidance configuration option:

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

   semverGuidance Options:

   • "patch" - Conservative mode: Only allows patch updates (~ prefix)
   • "minor" - Allows minor updates (^ prefix) in addition to patch
   • "auto" (default) - Automatically detects mode based on signatures in the project repo

   The rules for System Distributed Libraries require an ESLint JSON parser to parse the package.json and the addition of this parser to the .eslintrc (or .eslintrc.json). To install the parser (if you did not above):

   npm install -D jsonc-eslint-parser

   Then, in your ESLint config file, add the JSON parser for package.json:

    overrides: [
   {
     files: ['**/*.ts', '**/*.tsx'],
     parser: '@typescript-eslint/parser',
     parserOptions: {
       project: './tsconfig.json',
     },
   },
   {
     files: ['package.json'],
     parser: 'jsonc-eslint-parser',
   },
   ]

2. Specify formatter on lint tasks:

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

3. Run ESLint

   $ npm run lint

   Example:

   $ npm run lint
   
   > @amazon-devices/[email protected] lint
   > eslint src test --ext .ts,.tsx  --format node_modules/@amazon-devices/eslint-plugin-kepler/dist/formatters/default.js
   
   /Volumes/workspace/VegaSampleApp/src/components/Link.tsx
    32:5 ❌ 'useNativeDriver' property is set to 'false'.  Set useNativeDriver to 'true' to run animations on UI thread for better performance.  See https://developer.amazon.com/docs/vega/0.21/best_practices.html#the-animated-library for more. @amazon-devices/kepler/animated
    43:5 ⚠️ Subscription must be kept in variable so that it can be cleaned up on the component is detached.  See https://developer.amazon.com/docs/vega/0.21/best_practices.html#listeners-event-subscriptions-and-timers for more. @amazon-devices/kepler/check-subscription
    64:11 ⚠️ FlatList missing props: 'initialNumToRender,windowSize,removeClippedSubviews,maxToRenderPerBatch,updateCellsBatchingPeriod'.  FlatList performance is not fully unlocked without these props.  See https://developer.amazon.com/docs/vega/0.21/best_practices.html#flatlist for more. @amazon-devices/kepler/flat-list
   
    ⚠️ useReportFullyDrawn() call not found in project.  Add useReportFullyDrawn() in your App to accurately measure Time To Fully Drawn (TTFD) KPI.  See https://developer.amazon.com/docs/vega/0.21/measure-app-kpis.html#fully-drawn-marker for more. @amazon-devices/kepler/detect-report-fully-drawn
   
    ⚠️ usePreventHideSplashScreen() call not found in project.  Use usePreventHideSplashScreen() to natively render SplashScreen for better App launch performance.  See https://developer.amazon.com/docs/react-native-vega/0.72/splashscreenmanager.html for more. @amazon-devices/kepler/detect-splash-screen
   
   Summary:
    ❌ 1 error(s)
    ⚠️ 4 warning(s)
   
   Vega ESLint HTML report generated at: /Volumes/workspace/VegaSampleApp/generated/eslint-plugin-kepler/vega-eslint-report.html

4. Vega ESLint Plugin generated warnings will show in VS Code Editor when ESLint extension is installed.

   

5. Seeing errors and warnings in VSCode in the package.json requires an additional configuration step. In the VSCode settings.json file you will need to add json to the following entries, as shown:

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

System Distributed Library Rules

The plugin includes two rules for managing system distributed libraries:

@amazon-devices/kepler/sdl-package-version-check

Validates that SDL dependencies in package.json use proper semantic versioning:

• Patch only mode (semverGuidance: "patch"): Only allows patch updates using ~ prefix.
• Minor and patch mode (semverGuidance: "minor"): Allows minor updates using ^ prefix.
• Auto mode (semverGuidance: "auto"): Automatically detects based on signatures in the project repo. This is the default.

@amazon-devices/kepler/sdl-package-version-check-imports

Flags imports of system distributed libraries with informational messages to ensure developers understand the implications of using these libraries.

Backward Compatibility Rules

The plugin includes rules for managing backward compatibility in Vega library projects:

@amazon-devices/kepler/backward-compatibility

Validates that Vega library projects have proper version compatibility configuration:

• Checks for the existence of kepler-compatibility.json file in the project root
• Validates that the current package version is listed in the compatibility file
• Only runs in repositories with SDL project configuration

@amazon-devices/kepler/backward-compatibility-copy-on-pack

Ensures that the kepler-compatibility.json file is included in npm packages:

• Validates that kepler-compatibility.json is listed in the files array of package.json
• Only runs in repositories with SDL project configuration
• Required for proper version compatibility validation in published packages

@amazon-devices/kepler/package-migration

Validates that packages requiring migration to system distributed libraries are updated to newer versions:

• Checks specific packages that have been released as system distributed libraries
• Provides package version recommendations to make use of SDL released libs

API Privileges Rules

The plugin includes two rules for validating API privilege requirements:

@amazon-devices/kepler/api-privileges-check

Validates that APIs requiring permissions have the proper entries in the Vega manifest.toml file. Some Vega APIs require specific privileges to be declared in the manifest for the app to function correctly.

Supported privilege types:

• [[needs.privilege]] - Required privileges that must be present
• [[wants.privilege]] - Optional privileges that should be present

Example error:

Using the APIs in @amazon-devices/kepler-amazon-device-messaging requires the [[needs.privilege]] id="com.amazon.device-messaging.privilege.access" entry in the Vega manifest.toml.

The rule checks imports of known privilege-requiring packages and ensures the corresponding privilege entries exist in your project's manifest.toml file.

@amazon-devices/kepler/api-privilege-state-check

Validates that APIs requiring user privilege prompts have proper SecurityManager implementation. Some APIs require explicit user consent through privilege request dialogs.

Example error:

The API @amazon-devices/kepler-identifiers requires you prompt the user for privilige acceptance. See the Vega documentation for this API as well as for SecurityManager.