eslint-plugin-compat

Lint the browser compatibility of your code

demo of plugin usage

Setup

1. Install

npm install eslint-plugin-compat

2. Update ESLint Config

New Config (`eslint.config.mjs`)

import compat from "eslint-plugin-compat";

export default [compat.configs["flat/recommended"]];

Legacy Config (`.eslintrc.json`)

{
  "plugins": ["compat"],
  "extends": ["plugin:compat/recommended"],
  "env": {
    "browser": true,
  },
  // ...
}

3. Configure Target Browsers

Browser targets are configured using browserslist. You can configure browser targets in your package.json:

`package.json`

{
  // ...
  "browserslist": ["defaults"],
}

If no configuration is found, browserslist defaults to "> 0.5%, last 2 versions, Firefox ESR, not dead".

See browserslist/browserslist for more details.

Adding Polyfills

Add polyfills to the settings section of your eslint config. Append the name of the object and the property if one exists. Here are some examples:

{
  // ...
  "settings": {
    "polyfills": [
      // Example of marking entire API and all methods and properties as polyfilled
      "Promise",
      // Example of marking specific method of an API as polyfilled
      "WebAssembly.compile",
      // Example of API with no property (i.e. a function)
      "fetch",
      // Example of instance method, must add `.prototype.`
      "Array.prototype.push",
    ],
  },
}

Linting ES APIs (Experimental)

This plugin also supports linting the compatibility of ES APIs in addition to Web APIs. This is an experimental feature and is disabled by default. To enable this feature, add the following to your eslint config:

{
  // ...
  "settings": {
    "lintAllEsApis": true,
  },
}

Configuring for Different Environments

Browserslist allows specifying different browser queries for multiple environments. By default, this plugin targets the production browserslist environment. To change this default, set the settings.browserslistOpts.env property in your eslint config:

Example:

A browserslist with multiple environments:

  "browserslist": {
    "production": [
      "> 1%",
      "not dead"
    ],
    "modern": [
      "last 1 chrome version",
      "last 1 firefox version"
    ]
  }

Target modern browserslist environment:

{
  "settings": {
    "browserslistOpts": {
      "env": "modern",
    },
  },
}

Demo

For a minimal demo, see amilajack/eslint-plugin-compat-demo

Inspiration

Toolchains for native platforms, like iOS and Android, have had API linting from the start. It's about time that the web had similar tooling.

This project was inspired by a two hour conversation I had with someone on the experience of web development and if it is terrible or not. The premise they argued was that x browser doesn't support y feature while z browser does. Eventually, I agreed with him on this and made this plugin to save web developers from having to memorize the browser compatibility of WebAPIs.