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.

` javascript
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:
`javascript
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:
`javascript
module.exports = {
plugins: ["@amazon-devices/eslint-plugin-kepler"],
extends: ["plugin:@amazon-devices/eslint-plugin-kepler/kepler"],
}
`

You can also override severity of specific rules:
`javascript
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:

`javascript
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):

` bash
npm install -D jsonc-eslint-parser
`

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

` javascript
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:
`javascript
"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

`bash
$ npm run lint
`

Example:

`bash
$ npm run lint

> @amazon-devices/vega-sample-app@0.1.0 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.

![](./assets/checkSubscription.png)

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:

` javascript
"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:

$3


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.

$3

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:

$3

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

$3

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

$3

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:

$3

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.

$3

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.
``