gulp-eslint

What is gulp-eslint?

gulp-eslint is a Gulp plugin for ESLint, a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code. It helps developers maintain code quality by enforcing coding standards and detecting potential errors.

What are gulp-eslint's main functionalities?

Linting JavaScript files

This feature allows you to lint JavaScript files in your project. The code sample demonstrates how to set up a Gulp task that lints all JavaScript files except those in the node_modules directory, formats the linting results, and fails the task if any errors are found.

const gulp = require('gulp');
const eslint = require('gulp-eslint');

gulp.task('lint', () => {
  return gulp.src(['**/*.js', '!node_modules/**'])
    .pipe(eslint())
    .pipe(eslint.format())
    .pipe(eslint.failAfterError());
});

Custom ESLint configuration

This feature allows you to specify custom ESLint rules and environments directly within the Gulp task. The code sample shows how to configure ESLint to enforce single quotes and semicolons, and to recognize browser and Node.js environments.

const gulp = require('gulp');
const eslint = require('gulp-eslint');

gulp.task('lint', () => {
  return gulp.src(['**/*.js', '!node_modules/**'])
    .pipe(eslint({
      rules: {
        'quotes': ['error', 'single'],
        'semi': ['error', 'always']
      },
      envs: ['browser', 'node']
    }))
    .pipe(eslint.format())
    .pipe(eslint.failAfterError());
});

Linting specific files

This feature allows you to lint specific sets of files. The code sample demonstrates how to set up a Gulp task that only lints JavaScript files in the 'src/scripts' directory.

const gulp = require('gulp');
const eslint = require('gulp-eslint');

gulp.task('lint-scripts', () => {
  return gulp.src('src/scripts/**/*.js')
    .pipe(eslint())
    .pipe(eslint.format())
    .pipe(eslint.failAfterError());
});

Other packages similar to gulp-eslint

eslint

ESLint is the core tool for identifying and reporting on patterns found in ECMAScript/JavaScript code. It is highly configurable and can be used directly without Gulp. Compared to gulp-eslint, it provides more flexibility and can be integrated into various build systems and editors.

gulp-jshint

gulp-jshint is a Gulp plugin for JSHint, another popular JavaScript code quality tool. While JSHint is similar to ESLint, it is less configurable and has fewer rules. gulp-jshint is a good alternative if you prefer JSHint over ESLint.

gulp-standard

gulp-standard is a Gulp plugin for Standard, a JavaScript style guide, linter, and formatter. It enforces a specific set of coding standards without the need for configuration. Compared to gulp-eslint, it is less flexible but easier to set up for projects that follow the Standard style guide.

README

gulp-eslint

A gulp plugin for ESLint.

Installation

Use npm.

npm install gulp-eslint

Usage

var gulp = require('gulp'),
    eslint = require('gulp-eslint');

gulp.task('lint', function () {
    return gulp.src(['js/**/*.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());
});

gulp.task('default', ['lint'], function () {
    // This will only run if the lint task is successful...
});

Or use the plugin API to do things like:

gulp.src('js/**/*.js')
	.pipe(eslint({
		rulePaths: [
			'custom-rules/'
		],
		rules: {
			'my-custom-rule': 1,
			'strict': 2
		},
		globals: {
			'jQuery':false,
			'$':true
		},
		envs: [
			'browser'
		]
	}))
	.pipe(eslint.formatEach('compact', process.stderr));

API

eslint()

No explicit configuration. A .eslintrc file may be resolved relative to each linted file.

eslint(options)

options.rulePaths

Type: Array

A list of rules file paths rules to import. For more information about rules, see the ESLint rules.

Type: String (deprecated)

Load a single rules file.

Alias: rulesdir (deprecated)

options.configFile

Type: String

Path to the ESLint rules configuration file. For more information, see the ESLint CLI config option and Using Configuration Files.

options.reset

Type: Boolean

When true, ESLint will not include its default set of rules when configured.

options.useEslintrc

Type: Boolean

When false, ESLint will not load (http://eslint.org/docs/user-guide/configuring#using-configuration-files).

Alias: eslintrc (deprecated)

options.rules

Type: Object

Set configuration of rules.

{
	"rules":{
		"camelcase": 1,
		"comma-dangle": 2,
		"quotes": 0
	}
}

options.globals

Type: Object

Specify globals.

{
	"globals":{
		"jQuery": false,
		"$": true
	}
}

options.envs

Type: Array

Specify a list of environments to be applied.

Type: Object

Specify environments. Each key must match an existing env definition, and the key determines whether the env’s rules are applied (true) or not (false).

Alias: env (deprecated)

eslint(configFilePath)

Type: String

Shorthand for defining options.configFile.

eslint.failOnError()

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')
	.pipe(eslint())
	.pipe(eslint.failOnError())
	.pipe(gulp.dest('../output'));

eslint.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')
	.pipe(eslint())
	.pipe(eslint.failAfterError())
	.pipe(gulp.dest('../output'));

eslint.format(formatter, output)

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 process.cwd(), or as one of the ESLint-provided 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('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)

eslint.formatEach(formatter, output)

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.

##Configuration

ESLint may be configured explicity by using any of the following plugin options: config, rules, globals, or env. When not configured in this way, 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.

##Ignore Files

ESLint will ignore files that do not have a .js file extension at the point of linting (some plugins may change file extensions mid-stream). This avoids unintentional linting of non-JavaScript files.

ESLint will also detect an .eslintignore file when a directory passes through the pipeline. All subsequent files that pass through may be skipped if they match any pattern found in this file. The file may contain multiple globs as strings within a JSON array:

['**/*.min.js','output/**/*']