eslint-plugin-deprecation

3.0.0 verified Sat Apr 25 auth: no javascript

An ESLint plugin that reports usage of deprecated code by leveraging TypeScript type checking. Version 3.0.0 supports ESLint v8+ and TypeScript 4.2+ / 5.x. It automatically detects any code annotated with the JSDoc `@deprecated` tag, including APIs from your own code, libraries, Node.js, and browsers. Key differentiators: unlike simple regex-based checks, it uses the TypeScript compiler to accurately resolve deprecated symbols, avoiding false positives. The plugin ships with a recommended config and is maintained with frequent releases following semver. It requires a TypeScript parser with type information enabled.

Common errors

error TypeError: Cannot read properties of undefined (reading 'meta') ↓

cause Missing @typescript-eslint/utils dependency or incompatible version.

fix

Ensure you have installed @typescript-eslint/utils >=6.0.0 (for v2+) or >=7.0.0 (for v3+). Run: npm install @typescript-eslint/utils --save-dev

error ESLint: Failed to load plugin 'deprecation' declared in '.eslintrc.json': Cannot find module 'eslint-plugin-deprecation' ↓

cause Plugin not installed or not in node_modules.

fix

Install the plugin: npm install eslint-plugin-deprecation --save-dev

error Parsing error: The 'project' option in 'parserOptions' is not set. You must set it to a tsconfig.json path. ↓

cause Missing parserOptions.project required for TypeScript type-aware linting.

fix

Add in .eslintrc.json: "parserOptions": { "project": "./tsconfig.json" }

error Warning: The 'deprecation/deprecation' rule requires type information, but you have not set 'parserOptions.project'. The rule will be skipped. ↓

cause User did not configure TypeScript project path, causing the rule to be disabled.

fix

Set parserOptions.project as described above.

error Rule 'deprecation/deprecation' is not defined (ESLint configuration error) ↓

cause The plugin is not listed in the 'plugins' array.

fix

Add "deprecation" to the "plugins" array in your ESLint config.

Warnings

breaking Version 3.0.0 dropped support for ESLint v7. Projects still on ESLint v7 must stay on v2.x. ↓

fix Upgrade to ESLint v8+ or downgrade eslint-plugin-deprecation to v2.0.0.

breaking Version 2.0.0 dropped support for ESLint v6 and TypeScript <4.2. Users on older ESLint/TS must use v1.x. ↓

fix Upgrade ESLint to v7+ and TypeScript to v4.2+ or lock peer dependencies to v1.x.

deprecated Using require() to load the plugin in CommonJS projects is still supported but will be removed in future major versions. Migrate to ESM or dynamic import(). ↓

fix Use import or switch to ESM: `import deprecation from 'eslint-plugin-deprecation'`

gotcha The rule requires TypeScript type information to work. If your ESLint config does not set 'project' in parserOptions, the rule will silently fail (not report anything). ↓

fix Set `'project': './tsconfig.json'` in parserOptions and ensure the tsconfig includes the files being linted.

gotcha JSDoc @deprecated tags on ambient declarations (e.g., in .d.ts files) may not be detected if the type information is not loaded correctly. Ensure tsconfig includes ambient declarations. ↓

fix Include declarations in tsconfig or use a declaration file that is part of the project.

gotcha The rule does not check for deprecated usage in template literals or dynamic calls (e.g., `obj[deprecatedMethod]()`). Only static references are detected. ↓

fix Avoid dynamic access to deprecated APIs or use a separate lint rule for dynamic cases.

Install

npm install eslint-plugin-deprecation

yarn add eslint-plugin-deprecation

pnpm add eslint-plugin-deprecation

Imports

plugin

wrong

const { deprecation } = require('eslint-plugin-deprecation')

correct

module.exports = { plugins: ['deprecation'], rules: { 'deprecation/deprecation': 'error' } }

ESLint plugins are not imported as objects; they are specified as strings in the plugins array. The plugin registers the rule automatically.

Recommended Config
wrong
```
extends: ['deprecation/recommended']
```
correct
```
extends: ['plugin:deprecation/recommended']
```
The recommended config must be prefixed with 'plugin:' in the extends array. Omitting 'plugin:' will not resolve the config.
Rule 'deprecation/deprecation'
wrong
```
rules: { 'deprecation': 'error' }
```
correct
```
rules: { 'deprecation/deprecation': 'error' }
```
The rule is namespaced under the plugin name. Use 'deprecation/deprecation' or 'deprecation/deprecation' in the rules object.

Quickstart

Basic setup of ESLint with TypeScript parser and deprecation rule in .eslintrc.json, plus a TS file example showing the rule in action.

// Install dependencies:
// npm install --save-dev eslint @typescript-eslint/parser typescript eslint-plugin-deprecation

// .eslintrc.json
{
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": 2020,
    "sourceType": "module",
    "project": "./tsconfig.json"
  },
  "plugins": ["deprecation"],
  "rules": {
    "deprecation/deprecation": "error"
  }
}

// Example .ts file with a deprecated function:
/** @deprecated Use newFunction instead. */
function oldFunction() {}

oldFunction(); // ESLint will report: 'oldFunction' is deprecated. Use newFunction instead.