eslint-flat-config-utils

3.1.0 verified Sat Apr 25 auth: no javascript

Utils for managing and manipulating ESLint flat config arrays. Current stable version is 3.1.0, released actively by antfu. Provides helpers like concat (flatten and merge configs/promises), composer (chainable API for appending, prepending, inserting, renaming plugins, overriding rules, removing rules, and disabling rule fixes), and resolveExtends for extending configs. Differentiators: chainable composer extends Promise for direct use in eslint.config.mjs; renamePlugins, removeRules, disableRulesFix are unique helpers not found in standard ESLint utilities. ESM-only since v2.0.0, TypeScript-ready with shipped types, and supports @eslint/config-helpers for extends resolution since v3.0.0.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/eslint-flat-config-utils/index.mjs not supported. ↓

cause Package is ESM-only since v2.0.0; require() fails in CommonJS context.

fix

Use dynamic import() or switch to ESM: add 'type': 'module' to package.json and replace require() with import.

error TypeError: composer(...).append is not a function ↓

cause composer call not awaited or not properly chained after async operations.

fix

Ensure the composer chain is properly written: await composer(...).append(...); or use the fluent API synchronously.

error Cannot find module 'eslint-flat-config-utils' or its corresponding type declarations. ↓

cause Missing installation or TypeScript cannot resolve the package types.

fix

Install the package: npm install eslint-flat-config-utils. For TypeScript, ensure tsconfig.json includes 'moduleResolution': 'node' or 'bundler'.

error TypeError: Cannot destructure property 'concat' of '...' as it is undefined. ↓

cause Attempted to require() named export in CJS after v2.0.0, but package no longer exports CJS.

fix

Use import { concat } from 'eslint-flat-config-utils' or call dynamic import().

Warnings

breaking v2.0.0 dropped CommonJS support; now ESM-only. ↓

fix Convert require() to import statements and ensure package.json has 'type': 'module'.

deprecated v2.x resolveExtends behavior changed in v3.0.0 to require @eslint/config-helpers. ↓

fix Update code to use new resolveExtends signature or update imports if previously using older version.

gotcha composer.renamePlugins only applies to plugins and rules present in the config array; does not mutate original objects. ↓

fix Always await/reassign the composer result to get the renamed config.

gotcha disableRulesFix hijacks plugin's meta.fixable property; may not work with all plugins (e.g., those that cache fixable status). ↓

fix Test with targeted plugins; consider alternative like overriding rule options with meta.fixable: null if supported.

breaking v3.0.0 changed config resolution for extends; previous behavior (string extends) now handled by @eslint/config-helpers. ↓

fix Ensure @eslint/config-helpers is installed if using extends in config files.

Install

npm install eslint-flat-config-utils

yarn add eslint-flat-config-utils

pnpm add eslint-flat-config-utils

Imports

concat

wrong

const { concat } = require('eslint-flat-config-utils')

correct

import { concat } from 'eslint-flat-config-utils'

ESM-only since v2.0.0; require() will fail.

composer

wrong

import composer from 'eslint-flat-config-utils'

correct

import { composer } from 'eslint-flat-config-utils'

Default import is not available; composer is a named export.

ConfigNames

wrong

import { ConfigName } from 'eslint-flat-config-utils'

correct

import { ConfigNames } from 'eslint-flat-config-utils'

Type export for config names used in composer.override, etc. Plurals only.

resolveExtends
```
import { resolveExtends } from 'eslint-flat-config-utils'
```
Introduced in v3.0.0 to handle extends resolution via @eslint/config-helpers.

Quickstart

Chain composer to merge, rename and remove rules in ESLint flat config.

import { composer } from 'eslint-flat-config-utils'

const config = await composer(
  {
    name: 'base',
    plugins: {
      'my-plugin': { rules: { 'my-rule': 'error' } }
    },
    rules: {
      'my-plugin/my-rule': 'error'
    }
  },
  {
    name: 'typescript',
    files: ['*.ts'],
    rules: {
      'no-console': 'warn'
    }
  }
)
  .override('typescript', { rules: { 'no-console': 'off' } })
  .renamePlugins({ 'my-plugin': 'renamed' })
  .removeRules('no-console')

export default config