npm install gulp-eslint-new
const { src } = require('gulp');
const eslint = require('gulp-eslint-new');
// Define the default gulp task.
exports.default =
() => src(['scripts/*.js'])
// eslint() attaches the lint output to the "eslint" property of
// the file object so it can be used by other modules.
.pipe(eslint())
// eslint.format() outputs the lint results to the console.
// Alternatively use eslint.formatEach() (see Docs).
.pipe(eslint.format())
// To have the process exit with an error code (1) on lint error,
// return the stream and pipe to failAfterError last.
.pipe(eslint.failAfterError());
Or use the plugin API to do things like:
gulp.src(['**/*.js', '!node_modules/**'])
.pipe(eslint({
overrideConfig: {
rules: {
'my-custom-rule': 1,
'strict': 2
},
globals: {
jQuery: 'readonly',
$: 'readonly'
},
env: {
'browser': true
}
}
}))
.pipe(eslint.formatEach('compact', process.stderr));
For additional examples, look through the example directory.
No explicit configuration. A .eslintrc
file may be resolved relative to each linted file.
Param type: Object
Supported options include all linting options and autofix options of the ESLint
constructor.
Please, refer to the ESLint documentation for information about the usage of those options.
Check also the notes about the Autofix Function.
Additionally, gulp-eslint-new supports the options listed below.
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. options.overrideConfigFile
, options.resolvePluginsRelativeTo
, options.rulePaths
, options.overrideConfig.extends
, etc.).
The location of the files to be linted is not related to the working directory.
Type: boolean
When false
, .eslintignore files or ignore patterns in your configurations will not be respected.
Type: string | null
The path to a file ESLint uses instead of .eslintignore
in the current working directory.
Type: boolean
When true
, this option will filter warning messages from ESLint results. This mimics the ESLint CLI --quiet
option.
Type: (message, index, list) => boolean
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.
Type: boolean
When true
, add a result warning when ESLint ignores a file. This can be used to find files that are needlessly being loaded by gulp.src
. For example, since ESLint automatically ignores "node_modules" file paths and gulp.src
does not, a gulp task may take seconds longer just reading files from the "node_modules" directory.
The following options are provided for backward compatibility with gulp-eslint. Their usage is discouraged because preferable alternatives exist, that are more in line with the present ESLint conventions.
Type: string
A legacy synonym for options.overrideConfigFile
.
Type: string[]
Specify a list of environments to be applied.
Prefer using options.overrideConfig.env
instead. Note the different option name and format.
Type: string[]
Specify global variables to declare.
{
"globals": [
"jQuery",
"$"
]
}
Prefer using options.overrideConfig.globals
instead. Note the different format.
Type: string
Prefer using options.overrideConfig.parser
instead.
Type: Object
Prefer using options.overrideConfig.parserOptions
instead.
Type: Object
Set configuration of rules.
{
"rules": {
"camelcase": 1,
"comma-dangle": 2,
"quotes": 0
}
}
Prefer using options.overrideConfig.rules
instead.
Type: boolean
A legacy synonym for options.warnIgnored
.
When the fix
option is specified, fixes are applied to the gulp stream.
The fixed content can be saved to file using gulp.dest
(See example/fix.js).
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.
Param type: string
Shorthand for defining options.overrideConfigFile
.
Param type: (result) => 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(eslint())
.pipe(eslint.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)`);
}));
Type: (result, callback) => 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.
Type: result => 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.
Param type: (results) => 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.
errorCount |
number of errors |
warningCount |
number of warnings |
fixableErrorCount |
number of fixable errors |
fixableWarningCount |
number of fixable warnings |
fatalErrorCount |
number of fatal errors |
gulp.src(['**/*.js','!node_modules/**'])
.pipe(eslint())
.pipe(eslint.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, callback) => 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 => 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.
Stop a task/stream if an ESLint error has been reported for any file.
// Cause the stream to stop (fail) before copying an invalid JS file to the output directory.
gulp.src(['**/*.js','!node_modules/**'])
.pipe(eslint())
.pipe(eslint.failOnError());
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(eslint())
.pipe(eslint.failAfterError());
Format all linted files once. This should be used in the stream after piping through eslint
; otherwise, this will find no ESLint results to format.
The formatter
argument may be a string
, Function
, or undefined
. As a string
, a formatter module by that name or path will be resolved as a module, relative to the current working directory, or as one of the built-in ESLint formatters. If undefined
, the ESLint "stylish" formatter will be resolved. A Function
will be called with an Array
of file linting results to format.
// use the default "stylish" ESLint formatter
eslint.format()
// use the "checkstyle" ESLint formatter
eslint.format('checkstyle')
// use the "eslint-path-formatter" module formatter
// (@see https://github.com/Bartvds/eslint-path-formatter)
eslint.format('node_modules/eslint-path-formatter')
The output
argument may be a WritableStream
, Function
, or undefined
. As a WritableStream
, the formatter results will be written to the stream. If undefined
, the formatter results will be written to gulp's log. A Function
will be called with the formatter results as the only parameter.
// write to gulp's log (default)
eslint.format();
// write messages to stdout
eslint.format('junit', process.stdout)
Format each linted file individually. This should be used in the stream after piping through eslint
; otherwise, this will find no ESLint results to format.
The arguments for formatEach
are the same as the arguments for format
.
ESLint may be configured explicity by using any of the supported configuration options. Unless the useEslintrc
option is set to false
, ESLint will attempt to resolve a file by the name of .eslintrc
within the same directory as the file to be linted. If not found there, parent directories will be searched until .eslintrc
is found or the directory root is reached.
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 eslint.result
and eslint.results
methods are made available to support extensions and custom handling of ESLint results.