eslint-config-flat-gitignore

2.3.0 verified Sat Apr 25 auth: no javascript

ESLint flat config helper that automatically applies .gitignore patterns to ESLint's ignore list. Current stable version is 2.3.0, with monthly releases. Key differentiators: supports recursive .gitignore discovery (monorepos), git submodule detection via .gitmodules, strict mode (throws on missing ignore files by default), and the ability to specify custom ignore file paths. Only works with ESLint flat config (ESLint v9+). ESM-only since v2.0.0. Maintained by Anthony Fu.

Common errors

error ERR_REQUIRE_ESM: require() of ES Module /path/to/eslint-config-flat-gitignore/index.js from /path/to/project/eslint.config.js not supported. ↓

cause Using CommonJS require() on an ESM-only package (v2.0.0+).

fix

Change eslint.config.js to use import syntax, or rename to .mjs and use import.

error Error: Failed to load config 'flat-gitignore' to extend from. Referenced from: ... ↓

cause Incorrect import or config format (e.g., using extends array instead of flat config).

fix

Use flat config array: export default [ gitignore(), ... ] instead of extends.

error TypeError: gitignore is not a function ↓

cause Default import used incorrectly; e.g., import { gitignore } instead of import gitignore.

fix

Import default: import gitignore from 'eslint-config-flat-gitignore'

error Error: Cannot find module 'eslint-config-flat-gitignore' ↓

cause Package not installed or ESLint cannot resolve it in the config file.

fix

Run npm install eslint-config-flat-gitignore --save-dev and ensure node_modules is accessible.

Warnings

breaking ESM-only since v2.0.0: require() will fail with ERR_REQUIRE_ESM ↓

fix Use import instead of require, or upgrade to Node.js with --experimental-require-module (unstable).

breaking Requires ESLint v9+ with flat config; ESLint v8 or .eslintrc is not supported. ↓

fix Migrate to ESLint v9 flat config. See ESLint migration guide.

breaking Missing ignore file causes error by default (strict: true) since v1.0.0. ↓

fix Set strict: false if you expect .gitignore to be missing, or ensure the file exists.

gotcha recursive option added in v2.3.0; older versions ignore .gitignore in subdirectories. ↓

fix Upgrade to v2.3.0 and enable recursive: true for monorepo support.

gotcha Default only looks for .gitignore; .eslintignore is ignored unless explicitly added to files array. ↓

fix Pass files: ['.gitignore', '.eslintignore'] if you need both.

deprecated In v0.x, the module had a different API (name property, etc.); avoid using v0.x in new projects. ↓

fix Upgrade to v1 or later, update import and usage.

Install

npm install eslint-config-flat-gitignore

yarn add eslint-config-flat-gitignore

pnpm add eslint-config-flat-gitignore

Imports

default export (function)

wrong

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

correct

import gitignore from 'eslint-config-flat-gitignore'

Package is ESM-only since v2.0.0; no named exports. Use default import.

gitignore() options
wrong
```
gitignore({ files: ['.eslintignore'] })
```
correct
```
gitignore({ files: ['.gitignore'], strict: true })
```
By default, only .gitignore is looked for; add .eslintignore explicitly if needed.
gitignore with recursive option
wrong
```
gitignore({ recursive: true, skipDirs: ['dist'] })
```
correct
```
gitignore({ recursive: true })
```
In v2.3.0, recursive can be boolean or object with skipDirs; skipDirs matches directory names, not paths.

Quickstart

Shows basic setup: import the default function and call it as the first config item in ESLint flat config array.

// eslint.config.js
import gitignore from 'eslint-config-flat-gitignore'

export default [
  // Place gitignore first to ensure .gitignore patterns take precedence
  gitignore(),
  // Your other configs...
  {
    rules: {
      'no-console': 'warn'
    }
  }
]