ESLint Plugin for TypeScript Browser Compatibility

Common errors

• You have used a rule which requires parserServices to be generated. You must therefore provide a value for the "parserOptions.project" property for @typescript-eslint/parser.

  cause The `parserOptions.project` setting is missing or incorrectly configured in your `.eslintrc.json`, preventing the `@typescript-eslint/parser` from providing type information.
  fix Add `"parserOptions": { "project": "./tsconfig.json" }` (or the correct path to your `tsconfig.json`) to your ESLint configuration.

• Property 'includes' does not exist on type 'number[]'.

  cause This is a TypeScript compiler error, often seen when using modern ECMAScript features (like `Array.prototype.includes`) while your `tsconfig.json`'s `lib` option doesn't include the necessary ES version (e.g., `ES2016` or `ESNext`).
  fix Update your `tsconfig.json` `compilerOptions.lib` to include `ESNext` or the specific ES version that defines the feature, e.g., `"lib": ["ESNext", "DOM"]`.

• ESLint does not report compatibility issues despite using modern features (e.g., `Array.prototype.find`) with a target browser (e.g., `ie 11`) that doesn't support them.

  cause The `browserslist` configuration is either missing from `package.json` or a dedicated file, or it's incorrectly configured, leading the plugin to not know which browsers to target for compatibility checks.
  fix Ensure you have a valid `browserslist` configuration in your `package.json` (e.g., `"browserslist": ["ie 11"]`) or an `.browserslistrc` file at your project root.

Warnings

• gotcha The plugin requires `parserOptions.project` to be configured in your ESLint setup. Without it, the plugin cannot access TypeScript's type information, leading to errors or incomplete analysis.
  Fix: Ensure your `.eslintrc.json` includes `"parserOptions": { "project": "./tsconfig.json" }` pointing to your project's `tsconfig.json`.
• gotcha To correctly detect modern ECMAScript features (e.g., ES2016+), your `tsconfig.json`'s `compilerOptions.lib` array must include `ESNext` or specific ES versions that define these features. The default `lib` settings for `target: ES5` or `ES6` will not recognize newer APIs.
  Fix: Update your `tsconfig.json` to include `"lib": ["ESNext", "DOM"]` (or similar for your target environment) to ensure TypeScript recognizes the APIs you intend to use.
• gotcha Browser targets must be configured using `browserslist` (e.g., in `package.json`). If `browserslist` is missing or misconfigured, the plugin cannot determine which APIs are incompatible with your target environments, potentially leading to no warnings.
  Fix: Add a `browserslist` entry to your `package.json` (e.g., `"browserslist": ["ie 11", "last 2 versions"]`) or provide configuration via a dedicated `.browserslistrc` file.
• gotcha Currently, `eslint-plugin-typescript-compat` focuses solely on JavaScript Built-in Objects and their methods. It does not yet support checking for DOM API compatibility.
  Fix: Be aware that DOM API usage (e.g., `fetch`, `localStorage`) will not be linted for browser compatibility by this plugin at this time. Consider other tools for DOM API checks if needed.
• gotcha If your project uses polyfills for certain ECMAScript features, you must declare them in the `settings.polyfills` array in your ESLint configuration. Otherwise, the plugin will incorrectly flag these polyfilled features as incompatible.
  Fix: Add a `"settings": { "polyfills": ["Array.prototype.find", "Promise"] }` block to your `.eslintrc.json` to list all polyfilled APIs.

Install

• npm install eslint-plugin-typescript-compat npm
• yarn add eslint-plugin-typescript-compat yarn
• pnpm add eslint-plugin-typescript-compat pnpm

Imports

• plugin:typescript-compat/recommended
  wrong:

  import 'eslint-plugin-typescript-compat';

  correct:

  { "extends": ["plugin:typescript-compat/recommended"] }

  This is the primary method to enable the plugin's core rules and recommended settings within your `.eslintrc.json` file.
• typescript-compat/rule-name
  wrong:

  { "rules": { "no-unsupported-features": "error" } }

  correct:

  { "rules": { "typescript-compat/no-unsupported-features": "error" } }

  For fine-grained control or overriding specific rule settings, prefix the rule name with `typescript-compat/` in your `rules` configuration.
• settings.polyfills
  wrong:

  { "rules": { "typescript-compat/no-unsupported-features": ["error", { "polyfills": [...] }] } }

  correct:

  { "settings": { "polyfills": ["Array.prototype.find", "Promise"] } }

  To inform the plugin about features that are polyfilled in your project, preventing false positives, define them in the `settings.polyfills` array in your `.eslintrc.json`.

Quickstart

Demonstrates the installation and configuration of `eslint-plugin-typescript-compat` across `package.json`, `.eslintrc.json`, and `tsconfig.json`, then provides TypeScript code that will trigger browser compatibility warnings for features unsupported in Internet Explorer 11, based on the `browserslist` configuration.

/*
1. Install dependencies:
   npm install eslint-plugin-typescript-compat typescript @typescript-eslint/parser --save-dev

2. Configure your .eslintrc.json:
*/
// .eslintrc.json
/*
{
  "extends": ["plugin:typescript-compat/recommended"],
  "env": {
    "browser": true
  },
  "parserOptions": {
    "project": "./tsconfig.json"
  }
}
*/

/*
3. Configure your tsconfig.json to include a suitable 'lib' array:
*/
// tsconfig.json
/*
{
  "compilerOptions": {
    "target": "es5", // Or your desired target
    "lib": ["ESNext", "DOM"], // Must include ESNext to recognize modern features for linting
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*.ts"]
}
*/

/*
4. Configure your target browsers using browserslist in package.json:
*/
// package.json
/*
{
  "name": "my-project",
  "version": "1.0.0",
  "browserslist": [
    "ie 11",
    "last 2 versions",
    "> 0.2%"
  ]
}
*/

/*
5. Create an example TypeScript file (e.g., src/index.ts):
   Running ESLint on this file with the above config will flag features unsupported in IE 11.
*/

const items: number[] = [1, 2, 3];

// Array.prototype.includes is not supported in IE 11. Will trigger a warning.
items.includes(2);

// Array.prototype.find is also not supported in IE 11. Will trigger a warning.
const found = items.find((item) => item === 2);

// Math.sign is not supported in IE 11. Will trigger a warning.
const s = Math.sign(-5);

console.log(items, found, s);