grunt-eslint

26.0.0 verified Sat Apr 25 auth: no javascript

Grunt plugin to validate JavaScript files using ESLint. Current stable version is 26.0.0 (requires Node.js 20+ and Grunt >=1). Releases are feature-driven with major version bumps when ESLint or Node.js requirements change. Key differentiators: seamless integration with Grunt, supports both flat and legacy ESLint configs (flat is default since v25), dual console and file output (v26+), and feature flags for experimental ESLint features. Maintained by Sindre Sorhus with regular updates across major ESLint versions (6, 7, 8, 9).

Common errors

error Loading "grunt-eslint.js" tasks...ERROR >> Error: Cannot find module 'eslint' ↓

cause ESLint is not installed as a dependency (grunt-eslint does not include eslint internally; it must be installed separately).

fix

Run: npm install --save-dev eslint

error Warning: Task "eslint" not found. Use --force to continue. ↓

cause grunt-eslint not loaded; missing grunt.loadNpmTasks('grunt-eslint') or equivalent autoloader.

fix

Add grunt.loadNpmTasks('grunt-eslint'); to Gruntfile, or use a task loader like load-grunt-tasks.

error Fatal error: Invalid options in eslint task. Expected a configuration object, but got something else. ↓

cause Incorrect Grunt configuration; options for eslint are not properly nested under the target.

fix

Ensure structure: grunt.initConfig({ eslint: { options: { ... }, target: ['files'] } });

error Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@eslint/js' ↓

cause Flat config requires @eslint/js package for recommended configs, but it's not installed.

fix

Run: npm install --save-dev @eslint/js

Warnings

breaking Requires Node.js 20+ (v26.0.0) ↓

fix Upgrade Node.js to version 20 or later.

breaking Flat config is now required by default (v25.0.0) ↓

fix Migrate to flat config (e.g., use 'extends' option) or set ESLINT_USE_FLAT_CONFIG=false environment variable to use non-flat config (legacy).

gotcha outputFile option now also outputs to console (v26.0.0). Use silent: true to suppress console output. ↓

fix Add silent: true to options if you want output only to file (old behavior).

breaking Upgrade to ESLint 8 (v24.0.0): some options changed (e.g., configFile renamed to overrideConfigFile). ↓

fix Consult ESLint 8 documentation for options. In v24, overrideConfigFile replaces configFile. For v25+, use flat config 'extends'.

gotcha Options not documented in grunt-eslint README may have changed across ESLint versions. Always refer to ESLint Node.js API docs for available options. ↓

fix Check https://eslint.org/docs/developer-guide/nodejs-api for current ESLint options.

Install

npm install grunt-eslint

yarn add grunt-eslint

pnpm add grunt-eslint

Imports

grunt-eslint (Grunt task)
wrong
```
grunt.config('eslint', { options: {} });
```
correct
```
grunt.initConfig({ eslint: { target: ['file.js'] } });
```
The grunt-eslint package does not export any symbols; it registers the 'eslint' Grunt task. Use grunt.loadNpmTasks('grunt-eslint') or a loader like load-grunt-tasks.
load-grunt-tasks (optional loader)
wrong
```
grunt.loadTasks('node_modules/grunt-eslint/tasks');
```
correct
```
require('load-grunt-tasks')(grunt);
```
load-grunt-tasks is a convenience package that auto-loads all grunt plugins. It's not required but commonly used.
ESLint config (flat config)
wrong
```
grunt.initConfig({ eslint: { options: { configFile: '.eslintrc' } }, target: ['file.js'] });
```
correct
```
grunt.initConfig({ eslint: { options: { extends: [js.configs.recommended] } }, target: ['file.js'] });
```
Since v25, flat config is the default. Use 'extends' option with an array of configs. For legacy configs, set ESLINT_USE_FLAT_CONFIG environment variable to false.

Quickstart

Gruntfile.js example: registers eslint task, configures with recommended flat config, lints source and test JS files, runs via 'grunt lint' or 'grunt'.

// Install: npm install --save-dev grunt-eslint

module.exports = function(grunt) {
  require('load-grunt-tasks')(grunt);

  grunt.initConfig({
    eslint: {
      options: {
        extends: [require('@eslint/js').configs.recommended],
        format: 'stylish',
        quiet: false,
        maxWarnings: -1,
        failOnError: true
      },
      target: ['src/**/*.js', 'test/**/*.js']
    }
  });

  grunt.registerTask('lint', ['eslint']);
  grunt.registerTask('default', ['lint']);
};