no-deprecated-api

Prevent usage of deprecated APIs with migration context and timeline. This rule is part of eslint-plugin-conventions and provides LLM-optimized error messages with fix suggestions.

💡 Provides suggestions

Quick SummaryCopy Anchor Link

Error Message FormatCopy Anchor Link

The rule provides LLM-optimized error messages (Compact 2-line format) with actionable security guidance:

⚠️ [CWE-1078](https://cwe.mitre.org/data/definitions/1078.html) OWASP:A03 CVSS:5.3 | Deprecated API detected | MEDIUM
   Fix: Review and apply the recommended fix | https://owasp.org/Top10/A03_2021/

Message ComponentsCopy Anchor Link

Rule DetailsCopy Anchor Link

Reports every use of an API you list in apis, so a migration finishes instead of stalling. The configured names are matched as given:

• a call of the name (oldFetch(url)), also under a local name it was imported as (import { oldFetch as fetchIt } from 'lib'; fetchIt(url));
• constructing it (new OldClient());
• a member of that name on any object (api.oldFetch, api['oldFetch']).

The suggestion renames the use to replacement; it is not offered for a renamed import, where the import itself has to change. Nothing is reported while apis is empty (the default).

ConfigurationCopy Anchor Link

DeprecatedAPI ObjectCopy Anchor Link

ExamplesCopy Anchor Link

❌ IncorrectCopy Anchor Link

With apis: [{ name: 'oldFetch', replacement: 'newFetch', … }, { name: 'OldClient', replacement: 'Client', … }]:

import { oldFetch, OldClient } from 'my-library';
oldFetch(url);
new OldClient(url);
api.oldFetch(url);

✅ CorrectCopy Anchor Link

// Using replacement API
import { newFunction } from 'my-library';

newFunction({ data: 'test' });

Configuration ExamplesCopy Anchor Link

Library API DeprecationCopy Anchor Link

{
  rules: {
    'conventions/no-deprecated-api': ['error', {
      warnDaysBeforeRemoval: 90,
      apis: [
        {
          name: 'oldFetch',
          replacement: 'newFetch',
          deprecatedSince: '2024-01-01',
          removalDate: '2024-12-31',
          reason: 'Security improvements and better error handling',
          migrationGuide: 'https://docs.example.com/migration/fetch'
        },
        {
          name: 'legacyAuth',
          replacement: 'modernAuth',
          deprecatedSince: '2024-06-01',
          removalDate: '2025-06-01',
          reason: 'OAuth 2.0 compliance',
          migrationGuide: 'https://docs.example.com/migration/auth'
        }
      ]
    }]
  }
}

Internal API SunsetCopy Anchor Link

{
  rules: {
    'conventions/no-deprecated-api': ['warn', {
      warnDaysBeforeRemoval: 30,
      apis: [
        {
          name: 'UserService',
          replacement: 'CustomerService',
          deprecatedSince: '2024-10-01',
          removalDate: '2024-12-31',
          reason: 'Renamed to match ubiquitous language',
          migrationGuide: 'https://wiki.internal.com/customer-service-migration'
        }
      ]
    }]
  }
}

Why This MattersCopy Anchor Link

Comparison with AlternativesCopy Anchor Link

Related RulesCopy Anchor Link

• enforce-naming - Domain term enforcement
• react-class-to-hooks - React modernization
• no-unsafe-dynamic-require - Security enforcement

Further ReadingCopy Anchor Link

• CWE-1078: Deprecated Components - Official CWE entry
• API Deprecation Best Practices - Deprecation guidelines
• ESLint MCP Setup - Enable AI assistant integration

Known False NegativesCopy Anchor Link

• A reference that is not called or constructed (const f = oldFetch;, class X extends OldClient {}) is not reported where it is written.

Known False PositivesCopy Anchor Link

• Names are matched without their module: an API of the same name from a different library is reported too.

Use this rule

npm install -D oxlint-plugin-conventions

{  "jsPlugins": ["oxlint-plugin-conventions"],  "rules": {    "conventions/no-deprecated-api": "error"  }}

import { defineConfig } from 'vite-plus';export default defineConfig({  lint: {    jsPlugins: ['oxlint-plugin-conventions'],    rules: {      'conventions/no-deprecated-api': 'error',    },  },});