gulp-eslint-new ·

A gulp plugin to lint code with ESLint 8

Installation

Make sure that you are using a version of Node.js supported by ESLint 8. For TypeScript support, you need TypeScript 4.2 or later.

To install gulp-eslint-new, use npm:

npm i -D gulp-eslint-new

gulp-eslint-new will also install the latest version of ESLint 8, unless another one is found. To use a particular version of ESLint 8, install it by yourself. For example, to use ESLint 8.8.0:

npm i -D gulp-eslint-new eslint@8.8.0

Migrating

If you are migrating from gulp-eslint, you probably won't need to change any settings in your gulp task. gulp-eslint-new can handle most of the options used with gulp-eslint, although some of them are now deprecated in favor of a new name or format.

Anyway, since gulp-eslint-new uses ESLint 8 while gulp-eslint sticks to ESLint 6, you may need to make some changes to your project to address incompatibilities between the versions of ESLint. You can find more information at the links below.

• Breaking changes for users from ESLint 6 to ESLint 7
• Breaking changes for users from ESLint 7 to ESLint 8

Usage

const { src } = require('gulp');
const gulpESLintNew = require('gulp-eslint-new');

// Define the default gulp task.
exports.default =
() =>
src(['scripts/*.js'])                   // Read files.
.pipe(gulpESLintNew({ fix: true }))     // Lint files, create fixes.
.pipe(gulpESLintNew.fix())              // Fix files if necessary.
.pipe(gulpESLintNew.format())           // Output lint results to the console.
.pipe(gulpESLintNew.failAfterError());  // Exit with an error if problems are found.

Or use the plugin API to do things like:

gulp.src(['**/*.js', '!node_modules/**'])
.pipe
(
    gulpESLintNew
    (
        {
            overrideConfig:
            {
                env:        { browser: true, commonjs: true, jquery: true },
                extends:    ['eslint:recommended', 'plugin:jquery/slim'],
                globals:    { chrome: 'readonly' },
                plugins:    ['jquery'],
                rules:      { 'strict': 'error' },
            },
            warnIgnored: true,
        },
    ),
)
.pipe(gulpESLintNew.formatEach('compact', process.stderr));

For additional examples, look through the example directory.

API

gulpESLintNew()

Run ESLint with default settings. A configuration file may be resolved relative to each linted file.

gulpESLintNew(options)

Param type: Record<string, unknown>

Run ESLint with the specified options. All supported options are listed below. See the linked content for details about each option.

General options

• configType
• cwd

File enumeration options

• ignore
• ignorePath (not in flat config)
• ignorePatterns (flat config only)

Linting options

• allowInlineConfig
• baseConfig
• overrideConfig
• overrideConfigFile
• plugins
• reportUnusedDisableDirectives (not in flat config)
• resolvePluginsRelativeTo (not in flat config)
• rulePaths (not in flat config)
• useEslintrc (not in flat config)

Autofix options

• fix
• fixTypes

Reporting options

• quiet
• warnIgnored

General Options

options.configType

Type: "eslintrc" | "flat" | null

Newer versions of ESLint introduce a new type of configuration based on file eslint.config.js. Starting with gulp-eslint-new 1.7 it is possible to use the new configuration by setting the option configType to "flat".

When using the new configuration, the options ignorePath, reportUnusedDisableDirectives, resolvePluginsRelativeTo, rulePaths and useEslintrc are no longer supported. Legacy options are not supported either and will not be mapped to new options. Also, ignorePatterns is supported as a new top-level option, while other options like baseConfig, overrideConfig and overrideConfigFile accept different values. Refer to the official documentation for a description of all differences from the standard configuration.

options.cwd

Type: string

The working directory. This must be an absolute path. Default is the current working directory.

The working directory is where ESLint will look for a .eslintignore file by default. It is also the base directory for any relative paths specified in the options (e.g. overrideConfigFile, resolvePluginsRelativeTo, rulePaths, overrideConfig.extends, etc.). The location of the files to be linted is not related to the working directory.

File Enumeration Options

options.ignore

Type: boolean

When false, ESLint will not respect .eslintignore files or ignore patterns in your configurations.

options.ignorePath

Type: string

The path to a file ESLint uses instead of .eslintignore in the current working directory. This option in not available when configType is "flat".

options.ignorePatterns

Type: string[] | null

Ignore file patterns to use in addition to config ignores. This option in only available when configType is "flat".

Autofix Options

options.fix

Type: boolean | (message: LintMessage) => boolean

Set to true or a function to generate fixes when possible, or set to false to explicitly disable autofixing. If a predicate function is present, it will be invoked once for each lint message, and only the lint messages for which the function returned true will be reported.

See the Autofix section for more information and examples.

options.fixTypes

Type: ("directive" | "problem" | "suggestion" | "layout")[] | null

The types of fixes to apply. Default is all types.

Reporting Options

options.quiet

Type: boolean

When true, this option will filter warning messages from ESLint results. This mimics the ESLint CLI --quiet option.

Type: (message: LintMessage, index: number, list: LintMessage[]) => unknown

When a function is provided, it will be used to filter ESLint result messages, removing any messages that do not return a true (or truthy) value.

options.warnIgnored

Type: boolean

When true, add a result warning when ESLint ignores a file. Default is false.

This can be used to find files that are needlessly being loaded by gulp.src. For example, since ESLint automatically ignores file paths inside a node_modules directory but gulp.src does not, a gulp task may take seconds longer just reading files from node_modules.

Legacy Options

The following legacy options are provided for backward compatibility with gulp-eslint. Some of them used to be available as top-level options previously, but in current versions of ESLint, they must be specified as child properties of a baseConfig or overrideConfig object. When gulpESLintNew is passed any legacy options, it will map them automatically as shown in the table to match the new conventions.

If any legacy options are used, gulpESLintNew will print a warning. To remove the warning, replace the legacy options used in your gulp task with the new options.

gulpESLintNew(overrideConfigFile)

Param type: string

Shorthand for defining options.overrideConfigFile.

gulpESLintNew.result(action)

Param type: (result: Object) => void

Call a function for each ESLint file result. No returned value is expected. If an error is thrown, it will be wrapped in a gulp PluginError and emitted from the stream.

gulp.src(['**/*.js', '!node_modules/**'])
.pipe(gulpESLintNew())
.pipe
(
    gulpESLintNew.result
    (
        result =>
        {
            // Called for each ESLint result.
            console.log(`ESLint result: ${result.filePath}`);
            console.log(`# Messages: ${result.messages.length}`);
            console.log
            (
                `# Warnings: ${result.warningCount} (${
                result.fixableWarningCount} fixable)`,
            );
            console.log
            (
                `# Errors: ${result.errorCount} (${
                result.fixableErrorCount} fixable, ${
                result.fatalErrorCount} fatal)`,
            );
        },
    ),
);

Param Type: (result: Object, callback: Function) => void

Call an asynchronous, Node-style callback-based function for each ESLint file result. The callback must be called for the stream to finish. If an error is passed to the callback, it will be wrapped in a gulp PluginError and emitted from the stream.

Param Type: (result: Object) => Promise<void>

Call an asynchronous, promise-based function for each ESLint file result. If the promise is rejected, the rejection reason will be wrapped in a gulp PluginError and emitted from the stream.

gulpESLintNew.results(action)

Param type: (results: Object[]) => void

Call a function once for all ESLint file results before a stream finishes. No returned value is expected. If an error is thrown, it will be wrapped in a gulp PluginError and emitted from the stream.

The results list has additional properties that indicate the number of messages of a certain kind.

gulp.src(['**/*.js', '!node_modules/**'])
.pipe(gulpESLintNew())
.pipe
(
    gulpESLintNew.results
    (
        results =>
        {
            // Called once for all ESLint results.
            console.log(`Total Results: ${results.length}`);
            console.log
            (
                `Total Warnings: ${results.warningCount} (${
                results.fixableWarningCount} fixable)`,
            );
            console.log
            (
                `Total Errors: ${results.errorCount} (${
                results.fixableErrorCount} fixable, ${
                results.fatalErrorCount} fatal)`,
            );
        },
    ),
);

Param type: (results: Object[], callback: Function) => void

Call an asynchronous, Node-style callback-based function once for all ESLint file results before a stream finishes. The callback must be called for the stream to finish. If an error is passed to the callback, it will be wrapped in a gulp PluginError and emitted from the stream.

Param type: (results: Object[]) => Promise<void>

Call an asynchronous, promise-based function once for all ESLint file results before a stream finishes. If the promise is rejected, the rejection reason will be wrapped in a gulp PluginError and emitted from the stream.

gulpESLintNew.failOnError()

Stop a task/stream if an ESLint error has been reported for any file.

// Cause the stream to stop (fail) without processing more files.
gulp.src(['**/*.js', '!node_modules/**'])
.pipe(gulpESLintNew())
.pipe(gulpESLintNew.failOnError());

gulpESLintNew.failAfterError()

Stop a task/stream if an ESLint error has been reported for any file, but wait for all of them to be processed first.

// Cause the stream to stop (fail) when the stream ends if any ESLint error(s)
// occurred.
gulp.src(['**/*.js', '!node_modules/**'])
.pipe(gulpESLintNew())
.pipe(gulpESLintNew.failAfterError());

gulpESLintNew.format(formatter, writer)

formatter param type: string | Object | Function | undefined

writer param type: NodeJS.WritableStream | Function | undefined

Format all linted files once. This should be used in the stream after piping through gulpESLintNew; otherwise, this will find no ESLint results to format.

The formatter argument determines the ESLint formatter used to format linting results. If a string is provided, a formatter module by that name or path will be resolved. The resolved formatter will be either one of the built-in ESLint formatters, or a formatter exported by a module with the specified path (located relative to the ESLint working directory), or a formatter exported by a package installed as a dependency (the prefix "eslint-formatter-" in the package name can be omitted). Instead of providing a string, it is also possible to specify a formatter object as resolved by the ESLint method loadFormatter, or a formatter function directly. If this argument is undefined, a modified version of the ESLint "stylish" formatter will be used.

// Use the default gulp-eslint-new formatter.
gulpESLintNew.format()

// Use the "checkstyle" ESLint formatter.
gulpESLintNew.format('checkstyle')

// Use "eslint-formatter-pretty" as a formatter (must be installed with `npm`).
// See https://github.com/sindresorhus/eslint-formatter-pretty.
gulpESLintNew.format('pretty')

The writer argument may be a writable stream, Function, or undefined. As a writable stream, the formatter output will be written to the stream. If undefined, the formatter output will be written to gulp's log. A Function will be called with the formatter output as the only parameter.

// write to gulp's log (default)
gulpESLintNew.format()

// write messages to stdout
gulpESLintNew.format('junit', process.stdout)

gulpESLintNew.formatEach(formatter, writer)

formatter param type: string | Object | Function | undefined

writer param type: NodeJS.WritableStream | Function | undefined

Format each linted file individually. This should be used in the stream after piping through gulpESLintNew; otherwise, this will find no ESLint results to format.

The arguments for gulpESLintNew.formatEach are the same as the arguments for gulpESLintNew.format.

gulpESLintNew.fix()

Overwrite files with the fixed content provided by ESLint. This should be used in conjunction with the option fix in gulpESLintNew(options). Files without a fix and files that were not processed by ESLint will be left untouched.

See the Autofix section for more information and examples.

Autofix

ESLint can fix some lint problems automatically: this function is called autofix.

To enable autofix with gulp-eslint-new, set the option fix to true in gulpESLintNew(options), then pipe the stream to gulpESLintNew.fix(), e.g.

gulp.src(['**/*.{js,ts}', '!node_modules/**'])
.pipe(gulpESLintNew({ fix: true }))
.pipe(gulpESLintNew.fix());

See also the autofix examples.

The fix option applies fixes to the gulp stream. gulpESLintNew.fix() saves the fixed content to file. Rules that are fixable can be found in ESLint's rules list. When fixes are applied, a fixed property is set to true on the fixed file's ESLint result.

Custom Extensions

ESLint results are attached as an eslint property to the Vinyl files that pass through a gulp stream pipeline. This is available to streams that follow the initial gulp-eslint-new stream. The functions gulpESLintNew.result and gulpESLintNew.results are made available to support extensions and custom handling of ESLint results.