eslint-plugin-deprecation

What is eslint-plugin-deprecation?

The eslint-plugin-deprecation package is an ESLint plugin that helps developers identify and manage deprecated code in their JavaScript projects. It allows you to mark certain functions, methods, or properties as deprecated and provides warnings or errors when they are used.

What are eslint-plugin-deprecation's main functionalities?

Detect Deprecated Functions

This feature allows you to specify deprecated functions and provide a custom message. When the deprecated function is used, ESLint will warn the developer.

module.exports = {
  rules: {
    'deprecation/deprecation': [
      'warn',
      {
        'methods': {
          'myDeprecatedFunction': 'This function is deprecated. Use newFunction instead.'
        }
      }
    ]
  }
};

Detect Deprecated Properties

This feature allows you to mark object properties as deprecated. When the deprecated property is accessed, ESLint will issue a warning.

module.exports = {
  rules: {
    'deprecation/deprecation': [
      'warn',
      {
        'properties': {
          'myObject.oldProperty': 'This property is deprecated. Use newProperty instead.'
        }
      }
    ]
  }
};

Custom Deprecation Messages

This feature allows you to provide custom deprecation messages for both methods and properties, giving developers clear guidance on what to use instead.

module.exports = {
  rules: {
    'deprecation/deprecation': [
      'warn',
      {
        'methods': {
          'oldFunction': 'oldFunction is deprecated. Please use newFunction.'
        },
        'properties': {
          'oldProperty': 'oldProperty is deprecated. Please use newProperty.'
        }
      }
    ]
  }
};

Other packages similar to eslint-plugin-deprecation

eslint-plugin-deprecate

eslint-plugin-deprecate is an ESLint plugin that allows you to mark functions, methods, and properties as deprecated. It provides warnings when deprecated code is used. This package is similar to eslint-plugin-deprecation but may have different syntax and configuration options.

README

eslint-plugin-deprecation

An ESLint plugin with rules reporting usage of deprecated code

Prerequisites

If you already use TypeScript and one or more rules from the typescript-eslint plugin, then eslint-plugin-deprecation will work out of the box without any additional dependencies or special configuration specified in this section. (This is because @typescript-eslint/plugin automatically contains @typescript-eslint/parser and your ESLint should already be configured with the parserOptions to work properly with TypeScript.)

Otherwise, in order for you to use this plugin, you must also install the following dependencies:

• typescript
• @typescript-eslint/parser

For example, if you use the npm package manager, then you would run the following command in the root of your project:

npm install --save-dev typescript @typescript-eslint/parser

Next, you must configure ESLint to parse TypeScript and include type information:

{
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": 2020,
    "sourceType": "module",
    "project": "./tsconfig.json" // <-- Point to your project's "tsconfig.json" or create a new one.
  }
}

Install

For example, if you use the npm package manager, then you would run the following command in the root of your project:

npm install --save-dev eslint-plugin-deprecation

Setup

Using the recommended Config

The easiest way to use this plugin is to extend from the recommended config, like this:

{
  "extends": [
    "plugin:deprecation/recommended",
  ],
}

The recommended config will enable the plugin and enable the deprecation/deprecation rule with a value of error.

Manually Enable the Plugin and Rule

If you don't want to use the recommended config for some reason, you can accomplish the same thing by specifying the following config:

{
  "plugins": [
    "deprecation",
  ],

  "rules": {
    "deprecation/deprecation": "error",
  },
}

Rules

Disallow usage of deprecated APIs (deprecation/deprecation)

Reports usage of any code marked with a @deprecated JSDoc tag.

For example, this includes browser APIs, Node.js APIs, library APIs and any other code that is marked with this tag.

Rule Details

Examples of incorrect code for this rule:

import { parse } from 'node:url';
import cheerio from 'cheerio';

// Node.js API
const url = parse('/foo'); // ❌ 'parse' is deprecated. Use the WHATWG URL API instead. eslint(deprecation/deprecation)

// Browser API
console.log(event?.bubbles); // ❌ 'event' is deprecated. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/event) eslint(deprecation/deprecation)

// Deprecated library API
cheerio('<h2 class="title">Hello world</h2>'); // ❌ 'cheerio' is deprecated. Use the function returned by `load` instead. eslint(deprecation/deprecation)

Examples of correct code for this rule:

import { load } from 'cheerio';
import { ChangeEvent } from 'react';

// Node.js API
const url2 = new URL('/foo', 'http://www.example.com'); // ✅ Modern Node.js API, uses `new URL()`

// Browser API
function onClick(event: ChangeEvent<HTMLInputElement>) {
  console.log(event.bubbles); // ✅ Modern browser API, does not use global
}

// Library API
load('<h2 class="title">Hello world</h2>'); // ✅ Allowed library API, uses named `load` import

Credits

This rule was originally ported from the SonarJS repository.