Registry / testing / eslint-plugin-compat

eslint-plugin-compat

library7.0.1jsnpmunverified

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.

testing

npm install eslint-plugin-compat

github ↗package ↗

INSTALL

IMPORT

SIG · ESLINT-PLUGIN-COMP

eslint-plugin-compat

testingjavascriptv7.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

compat

✓ import compat from 'eslint-plugin-compat';

✗ const compat = require('eslint-plugin-compat');

ESLint flat configuration (eslint.config.mjs) primarily uses ESM imports. CommonJS `require` is generally discouraged for modern ESLint configs.

Config

✓ import type { Config } from 'eslint-plugin-compat';

Type import for advanced configuration scenarios when using TypeScript.

flat/recommended

✓ import compat from 'eslint-plugin-compat'; export default [compat.configs['flat/recommended']];

✗ export default [require('eslint-plugin-compat').configs.recommended];

Accessing the recommended flat configuration. Ensure your ESLint config is an ESM file (e.g., eslint.config.mjs).

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.

import compat from 'eslint-plugin-compat'; export default [ compat.configs['flat/recommended'], { // Optional: Configure target browsers via browserslist // This example sets a common baseline for broad compatibility. // A 'browserslist' key in package.json is usually preferred. settings: { browserslist: [ 'defaults', '> 0.5%', 'last 2 versions', 'Firefox ESR', 'not dead' ], // Optional: Mark polyfilled APIs to prevent warnings polyfills: [ 'Promise', 'WebAssembly.compile', 'fetch', 'Array.prototype.flat' ], // Optional: Enable experimental linting for ES APIs lintAllEsApis: false } } ];

Debug

Known issues

breakingVersion 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.

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.

affects: >=7.0.0

breakingVersion 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.

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.

affects: >=5.0.0

gotchaBy 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.

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.

affects: >=1.0.0

gotchaThe 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.

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.

affects: >=1.0.0

gotchaThe `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.

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.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Failed to load plugin 'compat' declared in 'eslint.config.mjs': Cannot find module 'eslint-plugin-compat'

The package `eslint-plugin-compat` is not installed or not resolvable by Node.js/ESLint.

fix

Run `npm install eslint-plugin-compat` or `yarn add eslint-plugin-compat` to install the package.

ESLint: Cannot read properties of undefined (reading 'configs')

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.

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+).

ESLint: 'Promise.allSettled' is not supported in Safari 13.0

The configured browserslist includes Safari 13.0, which does not support the `Promise.allSettled` API, and it has not been marked as polyfilled.

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.

TypeError: Invalid value for 'overrideConfigFile': Must be a string. Received null

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.

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).

Upgrade

Version history

7.0.1latest on npm

Audit

Dependencies

eslintrequiredPeer dependency for ESLint integration.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/amilajack/eslint-plugin-compat ↗

packagehttps://www.npmjs.com/package/eslint-plugin-compat ↗