eslint-flat-config-utils

Utils for managing and manipulating ESLint flat config arrays

Documentation

Install

npm i eslint-flat-config-utils

Utils

Most of the descriptions are written in JSDoc, you can find more details in the documentation via JSR.

Here listing a few highlighted ones:

concat

Concatenate multiple ESLint flat configs into one, resolve the promises, and flatten the array.

// eslint.config.mjs
import { concat } from 'eslint-flat-config-utils'

export default concat(
  {
    plugins: {},
    rules: {},
  },
  // It can also takes a array of configs:
  [
    {
      plugins: {},
      rules: {},
    }
    // ...
  ],
  // Or promises:
  Promise.resolve({
    files: ['*.ts'],
    rules: {},
  })
  // ...
)

composer

Create a chainable composer that makes manipulating ESLint flat config easier.

It extends Promise, so that you can directly await or export it to eslint.config.mjs

// eslint.config.mjs
import { composer } from 'eslint-flat-config-utils'

export default composer(
  {
    plugins: {},
    rules: {},
  }
  // ...some configs, accepts same arguments as `concat`
)
  .append(
    // appends more configs at the end, accepts same arguments as `concat`
  )
  .prepend(
    // prepends more configs at the beginning, accepts same arguments as `concat`
  )
  .insertAfter(
    'config-name', // specify the name of the target config, or index
    // insert more configs after the target, accepts same arguments as `concat`
  )
  .renamePlugins({
    // rename plugins
    'old-name': 'new-name',
    // for example, rename `n` from `eslint-plugin-n` to more a explicit prefix `node`
    'n': 'node'
    // applies to all plugins and rules in the configs
  })
  .override(
    'config-name', // specify the name of the target config, or index
    {
      // merge with the target config
      rules: {
        'no-console': 'off'
      },
    }
  )

// And you can directly return the composer object to `eslint.config.mjs`

[!NOTE]
From version 3.0.0, the composer function also expands the configs with defineConfig from eslint/config which supports extends property.

composer.renamePlugins

This helper renames plugins in all configurations in the composer. It is useful when you want to enforce a plugin to a custom name:

const config = await composer([
  {
    plugins: {
      n: pluginN,
    },
    rules: {
      'n/foo': 'error',
    }
  }
])
  .renamePlugins({
    n: 'node'
  })

// The final config will have `node/foo` rule instead of `n/foo`

composer.removeRules

This helper removes specified rules from all configurations in the composer. It is useful when you are certain that these rules are not needed in the final configuration. Unlike overriding with off, removed rules are not affected by priority considerations.

const config = await composer([
  {
    rules: {
      'foo/bar': 'error',
      'foo/baz': 'warn',
    }
  },
  {
    files: ['*.ts'],
    rules: {
      'foo/bar': 'off',
    }
  }
  // ...
])
  .removeRules(
    'foo/bar',
    'foo/baz',
  )

// The final config will not have `foo/bar` and `foo/baz` rules at all

composer.disableRulesFix

This helper hijack plugins to make fixable rules non-fixable, useful when you want to disable auto-fixing for some rules but still keep them enabled.

For example, if we want the rule to error when we use let on a const, but we don’t want auto-fix to change it to const automatically:

const config = await composer([
  {
    plugins: {
      'unused-imports': pluginUnusedImports,
    },
    rules: {
      'perfer-const': 'error',
      'unused-imports/no-unused-imports': 'error',
    }
  }
])
  .disableRulesFix(
    [
      'prefer-const',
      'unused-imports/no-unused-imports',
    ],
    {
      // this is required only when patching core rules like `prefer-const` (rules without a plugin prefix)
      builtinRules: () => import('eslint/use-at-your-own-risk').then(r => r.builtinRules),
    },
  )

[!NOTE]
This function mutate the plugin object which will affect all the references to the plugin object globally. The changes are not reversible in the current runtime.

composer.setDefaultIgnores

Sets default ignores globs for configs that have rules but no explicit scoping (files, ignores, or language). Useful when mixing fundamentally different languages (e.g. JS + Markdown) and you want global rule configs to not “leak” into a foreign language whose SourceCode lacks JS-only methods.

The callback receives the composer’s previously-accumulated globs and returns the new list, so calls compose:

const config = await composer([
  // gains `ignores: ['**/*.md']`
  { rules: { 'no-irregular-whitespace': 'error' } },
  // explicit `files`, untouched
  { files: ['**/*.md'], rules: { 'markdown/heading-increment': 'error' } },
])
  .setDefaultIgnores(() => ['**/*.md'])
  .setDefaultIgnores(prev => [...prev, '**/*.json']) // additive

Configs without rules (plugins-only, languageOptions-only, setup blocks) are left as-is. Configs already scoped (with files, ignores, or language set) are also left as-is.

When a sub-composer is appended into another via append/prepend/insertBefore/insertAfter/replace, the parent absorbs the child’s accumulated globs at append time — so a default-ignores declared on the inner composer also protects the parent’s other unscoped configs.

extend

Extend another flat config from a different root, and rewrite the glob paths accordingly:

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

export default [
  ...await extend(
    import('./sub-package/eslint.config.mjs'),
    './sub-package/'
  )
]

Sponsors

License

MIT License © 2023-PRESENT Anthony Fu