@exadel/eslint-plugin-esl

ESL migration support

Authors: Natalia Smirnova, Alexey Stsefanovich (ala'n).

This article aims to assist the smooth migration process from older versions of ESL to the latest version. To support this transition, we have developed an ESLint plugin designed specifically for ESL library. This plugin targets deprecated features and aliases within the library, offering a seamless means of identifying these outdated elements. Additionally, it suggests suitable replacements, thereby ensuring a hassle-free upgrade to the newest version of ESL.

Installation

Note: Before installing the plugin, ensure that you have the ESLint package of version 8.0.0 or higher. If you do not intend to install ESLint, this article may not as helpful. However, there are deprecated features listed in the Rules section, that may assist in manual migration. Alternatively, see our Release notes.

To use custom ESLint plugin, you need to install it as npm package:

npm install --save-dev @exadel/eslint-plugin-esl

Once installed, the plugin needs to be added in eslint configuration file:

{
  // ...
  "plugins": [
    "@exadel/esl"
  ]
  // ...
}

Or in YAML:

  plugins: 
    - "@exadel/esl"

Configuration

We strongly recommend using a built-in preset tailored to your specific needs:

• If you use ESL version 4 and wish to receive notifications about ESL best practices and deprecations with a lighter approach, we recommend using the default-4.0 preset. It is configured to display all recommendations as warnings. Provide the following line to extend the section of eslint configuration: plugin:@exadel/esl/default-4
• If you want to stay up-to-date and be prepared for ESL version 5, consider using the default-5.0 preset. It treats all items on the deprecation list with the error severity. Provide the following line to extend the section of eslint configuration: plugin:@exadel/esl/default-5

However, you still have the option to manually manage the rules if needed.

Note: All the rules in our custom ESLint plugin are auto-correctable. This means you can take advantage of ESLint's --fix option to perform automatic adjustments to your code.

Rules

The ESLint plugin provides a separate rule for each deprecated utility within the ESL project, that's considered to be deprecated. Below is the list of them:

• @exadel/esl/deprecated-4/alert-action-params - Rule for deprecated AlertActionParams alias for ESLAlertActionParams.

• @exadel/esl/deprecated-4/generate-uid - Rule for deprecated generateUId alias for randUID.

• @exadel/esl/deprecated-4/deep-compare - Rule for deprecated deepCompare alias for isEqual.

• @exadel/esl/deprecated-4/event-utils - Rule for deprecated EventUtils alias for ESLEventUtils.

• @exadel/esl/deprecated-4/panel-action-params - Rule for deprecated PanelActionParams alias for ESLPanelActionParams.

• @exadel/esl/deprecated-4/popup-action-params - Rule for deprecated PopupActionParams alias for ESLPopupActionParams.

• @exadel/esl/deprecated-4/traversing-query - Rule for deprecated TraversingQuery alias for ESLTraversingQuery.

• @exadel/esl/deprecated-4/toggleable-action-params - Rule for deprecated ToggleableActionParams alias for ESLToggleableActionParams.

• @exadel/esl/deprecated-4/tooltip-action-params - Rule for deprecated TooltipActionParams alias for ESLTooltipActionParams.

• @exadel/esl/deprecated-4/base-decorators-path - Rule for deprecated @attr, @prop, @boolAttr, @jsonAttr, @listen import paths.

• @exadel/esl/deprecated-5/alert-action-params - Rule for deprecated AlertActionParams alias for ESLAlertActionParams.

• @exadel/esl/deprecated-5/panel-action-params - Rule for deprecated PanelActionParams alias for ESLPanelActionParams.

• @exadel/esl/deprecated-5/popup-action-params - Rule for deprecated PopupActionParams alias for ESLPopupActionParams.

• @exadel/esl/deprecated-5/tooltip-action-params - Rule for deprecated TooltipActionParams alias for ESLTooltipActionParams.

These rules can be configured manually inside the rules section of your ESLint configuration file.

Running ESL ESLint with CLI (without ESLint installed)

⚠️ Note: This approach is not recommended. If you use ESL, consider installing ESLint with the ESL plugin and keep it in your project.

If you do not have ESLint installed, you can still run ESL ESLint with the following command:

npm i -g eslint @babel/eslint-parser @typescript-eslint/parser
npx eslint --plugin @exadel/esl --no-eslintrc --config https://raw.githubusercontent.com/exadel-inc/esl/main/eslint/eslint/defaults/ts-config-default.eslint.yml --ext .js,.ts,.jsx,.tsx .

There are a couple of basic configurations:

• defaults/es-config-default.eslint.yml
• defaults/ts-config-default.eslint.yml Note: You may still need to configure them temporarily in the root of the project to ensure ESLint can parse your code correctly.