eslint-compat-utils

0.6.5 verified Sat Apr 25 auth: no javascript

Provides a backward-compatible API for ESLint custom rules that works with both ESLint v9 (flat config) and older ESLint versions (v6–v8). Current stable version is 0.6.5, released in 2024. The package is experimental but actively maintained with monthly patches. Key differentiator: it offers polyfills for new ESLint APIs (like getSourceCode, getScope, RuleTester shims) so rule authors can write modern code without dropping support for older ESLint installations. Ships TypeScript definitions.

Common errors

error Cannot find module 'eslint-compat-utils' ↓

cause Package not installed or missing from node_modules.

fix

Run: npm install eslint-compat-utils --save-dev

error TypeError: eslint_compat_utils_1.getSourceCode is not a function ↓

cause Trying to import ESM style with 'import', but package exports CJS only.

fix

Change to: const { getSourceCode } = require('eslint-compat-utils');

error Error: eslint-compat-utils is not compatible with eslint version x.x.x ↓

cause ESLint version is below 6.0.0 or above supported range.

fix

Upgrade eslint to >=6.0.0 and <10.0.0.

Warnings

deprecated Package is still experimental; API may change in minor versions. ↓

fix Pin to exact version or use stable alternatives like eslint-plugin-eslint-comments.

breaking getScope() and other modern source code methods may behave differently or throw on older ESLint versions. ↓

fix Test rules against target ESLint versions; consider using try-catch for fallback.

gotcha No ESM support – using import instead of require results in TypeError. ↓

fix Use CommonJS require() or set up bundler to handle CJS.

gotcha getPhysicalFilename may return incorrect values for ESLint <7.28.0. ↓

fix Prefer getFilename() if physical filename is not critical.

Install

npm install eslint-compat-utils

yarn add eslint-compat-utils

pnpm add eslint-compat-utils

Imports

getSourceCode
wrong
```
import { getSourceCode } from 'eslint-compat-utils'
```
correct
```
const { getSourceCode } = require('eslint-compat-utils')
```
Package does not ship native ESM; use CJS require or configure bundler to handle CJS. ESM support is planned but not yet implemented. Always use require().

getCwd

wrong

const getCwd = require('eslint-compat-utils').default

correct

const { getCwd } = require('eslint-compat-utils')

No default export; import named exports only.

getFilename

wrong

import { getFilename } from 'eslint-compat-utils'

correct

const { getFilename } = require('eslint-compat-utils')

Same as above — CJS only for now.

Quickstart

Shows an ESLint rule that uses getSourceCode and getFilename from eslint-compat-utils to remain compatible with ESLint v6–v9.

// eslint rule using eslint-compat-utils
const { getSourceCode, getFilename } = require('eslint-compat-utils');

module.exports = {
  meta: {
    type: 'suggestion',
    docs: {
      description: 'disallow use of process.env',
    },
    fixable: null,
    schema: [],
  },
  create(context) {
    const sourceCode = getSourceCode(context);
    const filename = getFilename(context);
    return {
      MemberExpression(node) {
        if (
          node.object.type === 'Identifier' &&
          node.object.name === 'process' &&
          node.property.type === 'Identifier' &&
          node.property.name === 'env'
        ) {
          context.report({
            node,
            message: 'Unexpected use of process.env in {{filename}}.',
            data: { filename },
          });
        }
      },
    };
  },
};