{"id":13141,"library":"eslint-plugin-compat","title":"ESLint Plugin for Browser Compatibility","description":"eslint-plugin-compat is an ESLint plugin designed to lint the browser compatibility of JavaScript APIs used in your codebase. It leverages `caniuse` data and `browserslist` configurations to identify code that targets APIs unsupported by your specified browsers. The current stable version is 7.0.1, released as of March 2026, with a relatively frequent release cadence, often seeing multiple minor or patch releases per month, alongside periodic major updates for ESLint compatibility. Key differentiators include its tight integration with the `browserslist` ecosystem, allowing developers to define target environments consistently across various tools, and its explicit support for marking polyfilled APIs, preventing false positives. It's an essential tool for maintaining robust frontend code that functions reliably across diverse browser landscapes.","status":"active","version":"7.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/amilajack/eslint-plugin-compat","tags":["javascript","eslint","browser","support","api","lint","caniuse","kangax","typescript"],"install":[{"cmd":"npm install eslint-plugin-compat","lang":"bash","label":"npm"},{"cmd":"yarn add eslint-plugin-compat","lang":"bash","label":"yarn"},{"cmd":"pnpm add eslint-plugin-compat","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for ESLint integration.","package":"eslint","optional":false}],"imports":[{"note":"ESLint flat configuration (eslint.config.mjs) primarily uses ESM imports. CommonJS `require` is generally discouraged for modern ESLint configs.","wrong":"const compat = require('eslint-plugin-compat');","symbol":"compat","correct":"import compat from 'eslint-plugin-compat';"},{"note":"Type import for advanced configuration scenarios when using TypeScript.","symbol":"Config","correct":"import type { Config } from 'eslint-plugin-compat';"},{"note":"Accessing the recommended flat configuration. Ensure your ESLint config is an ESM file (e.g., eslint.config.mjs).","wrong":"export default [require('eslint-plugin-compat').configs.recommended];","symbol":"flat/recommended","correct":"import compat from 'eslint-plugin-compat'; export default [compat.configs['flat/recommended']];"}],"quickstart":{"code":"import compat from 'eslint-plugin-compat';\n\nexport default [\n  compat.configs['flat/recommended'],\n  {\n    // Optional: Configure target browsers via browserslist\n    // This example sets a common baseline for broad compatibility.\n    // A 'browserslist' key in package.json is usually preferred.\n    settings: {\n      browserslist: [\n        'defaults',\n        '> 0.5%',\n        'last 2 versions',\n        'Firefox ESR',\n        'not dead'\n      ],\n      // Optional: Mark polyfilled APIs to prevent warnings\n      polyfills: [\n        'Promise',\n        'WebAssembly.compile',\n        'fetch',\n        'Array.prototype.flat'\n      ],\n      // Optional: Enable experimental linting for ES APIs\n      lintAllEsApis: false\n    }\n  }\n];","lang":"typescript","description":"This quickstart demonstrates setting up `eslint-plugin-compat` using ESLint's flat configuration system (`eslint.config.mjs`). It imports the recommended flat configuration and shows how to configure target browsers and polyfills directly within the config, although a `browserslist` file or `package.json` entry is often preferred for browser targets."},"warnings":[{"fix":"Upgrade ESLint to version `^9.0.0 || ^10.0.0` in your project's `package.json`. If using ESLint 8 or older, you must either upgrade ESLint or remain on `eslint-plugin-compat` v6.x.","message":"Version 7.0.0 of `eslint-plugin-compat` dropped support for ESLint versions 4-8. Users must upgrade their ESLint installation to version 9.0.0 or higher.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"For new projects or when migrating, adopt the `eslint.config.mjs` flat configuration setup. If sticking with legacy `.eslintrc.*` files, use `plugin:compat/recommended` and adjust import paths accordingly.","message":"Version 5.0.0 introduced support for ESLint's flat configuration. While it maintains backward compatibility with legacy `eslintrc` files, new projects or migrations should use the flat config format as shown in the quickstart.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"To lint these conditionals, set `settings.ignoreConditionalChecks` to `true` in your ESLint configuration. This will force `eslint-plugin-compat` to report on API usage even within `if` statements.","message":"By default, conditional checks for API existence (e.g., `if (fetch) { ... }`) do not trigger a compatibility report. This can hide potential issues if the conditional logic isn't robust or the fallback is insufficient.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"To enable ES API linting, set `settings.lintAllEsApis` to `true` in your ESLint configuration. Monitor upstream releases for stability and potential breaking changes related to this feature.","message":"The linting of ES APIs (e.g., `Promise.allSettled`) is an experimental feature and is disabled by default. Relying on it without careful testing might lead to unexpected behavior or missed compatibility issues.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always define your target browsers explicitly using a `browserslist` key in `package.json` or a `.browserslistrc` file. Ensure it reflects your project's actual browser support requirements.","message":"The `browserslist` configuration is crucial for accurate compatibility checks. If no `browserslist` configuration is found in your `package.json` or `.browserslistrc`, the plugin defaults to `'> 0.5%, last 2 versions, Firefox ESR, not dead'`, which might not align with your actual target audience.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install eslint-plugin-compat` or `yarn add eslint-plugin-compat` to install the package.","cause":"The package `eslint-plugin-compat` is not installed or not resolvable by Node.js/ESLint.","error":"Error: Failed to load plugin 'compat' declared in 'eslint.config.mjs': Cannot find module 'eslint-plugin-compat'"},{"fix":"Ensure you are using `import compat from 'eslint-plugin-compat';` for ESLint flat config (`eslint.config.mjs`) and that your ESLint version supports flat config (ESLint 9+).","cause":"This usually indicates `eslint-plugin-compat` was imported incorrectly, or ESLint is running in an environment where `compat` is not properly defined, possibly due to a CommonJS/ESM mismatch.","error":"ESLint: Cannot read properties of undefined (reading 'configs')"},{"fix":"Either update your `browserslist` configuration to exclude browsers that don't support `Promise.allSettled`, or add `'Promise.allSettled'` to the `settings.polyfills` array in your ESLint config.","cause":"The configured browserslist includes Safari 13.0, which does not support the `Promise.allSettled` API, and it has not been marked as polyfilled.","error":"ESLint: 'Promise.allSettled' is not supported in Safari 13.0"},{"fix":"Ensure your `eslint.config.mjs` file is correctly formatted and discoverable. Check your ESLint extension settings in your IDE to ensure it's pointing to the correct config file type (flat vs. legacy).","cause":"This error often occurs when an ESLint related tool (e.g., VS Code extension) is trying to resolve configuration and fails to find a valid ESLint config file, or there's a misconfiguration in how ESLint is initialized.","error":"TypeError: Invalid value for 'overrideConfigFile': Must be a string. Received null"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}