Gulp ESLint and Stylelint
last modified November 15, 2026
In this article we lint JavaScript and CSS in Gulp 5 tasks with ESLint and Stylelint. The tasks print the problems, fail the build when there are errors, and can fix the simple ones automatically.
Linting in a build
A linter finds mistakes and style problems without running the code. In an editor it gives immediate feedback, but only a check
in the build guarantees that nothing slips through: when a linting task fails, the tasks after it do not run, and a CI job
fails too. We use ESLint for JavaScript and Stylelint for CSS, with the
plugins gulp-eslint-new and gulp-stylelint-esm. The older plugins gulp-eslint and
gulp-stylelint do not work with the current versions of the linters.
Installing the project
We create an ES module project and install Gulp, ESLint with its recommended rules and the globals package, Stylelint with the
standard configuration, and the two plugins. The versions used here are ESLint 10, Stylelint 17, gulp-eslint-new 2.6 and
gulp-stylelint-esm 3.0.
$ mkdir gulp-lint $ cd gulp-lint $ npm init -y $ npm pkg set type=module $ npm i -D gulp eslint @eslint/js globals stylelint stylelint-config-standard gulp-eslint-new gulp-stylelint-esm $ mkdir -p src/js src/css
The configuration
ESLint reads a flat configuration from eslint.config.js. We start with the recommended rules and for the files in src/js we
declare the browser globals such as document and add three rules: no-console as a warning, and
eqeqeq and semi as errors. Stylelint reads .stylelintrc.json, which extends the standard configuration.
import js from '@eslint/js';
import globals from 'globals';
export default [
js.configs.recommended,
{
files: ['src/js/**/*.js'],
languageOptions: { globals: globals.browser },
rules: {
'no-console': 'warn',
eqeqeq: 'error',
semi: ['error', 'always']
}
}
];
{
"extends": "stylelint-config-standard"
}
The difference between a warning and an error matters later: warnings are printed, but they do not fail a task.
The sources with problems
The two files contain mistakes on purpose: an unused variable, a loose comparison, a console statement and a missing semicolon in the script; a unit after zero, a duplicated declaration in the stylesheet.
const greeting = 'Hello';
let unused = 42;
function show(value) {
if (value == null) {
console.log('nothing')
}
document.title = greeting + ' ' + value;
}
show('Gulp');
body {
color: #FFF;
margin: 0px;
}
a {
color: red;
color: red;
}
The linting tasks
The lintJs task passes the files through eslint(), which attaches the results to each file, then
eslint.format() prints them and eslint.failAfterError() fails the task if any file has an error. The failure is
at the end, so all files are reported first. The lintCss task is shorter: the plugin
does the linting and the reporting, and the failAfterError option makes it fail. The reporters option selects the
string formatter and sends it to the console. The lint task runs both in parallel,
see Gulp series and parallel.
import { src, dest, series, parallel, watch } from 'gulp';
import eslint from 'gulp-eslint-new';
import gulpStylelint from 'gulp-stylelint-esm';
export function lintJs() {
return src('src/js/**/*.js')
.pipe(eslint())
.pipe(eslint.format())
.pipe(eslint.failAfterError());
}
export function lintCss() {
return src('src/css/**/*.css')
.pipe(gulpStylelint({
failAfterError: true,
reporters: [{ formatter: 'string', console: true }]
}));
}
export const lint = parallel(lintJs, lintCss);
export function fixJs() {
return src('src/js/**/*.js')
.pipe(eslint({ fix: true }))
.pipe(eslint.fix())
.pipe(eslint.format())
.pipe(dest('src/js'));
}
export function fixCss() {
return src('src/css/**/*.css')
.pipe(gulpStylelint({ fix: true, reporters: [] }))
.pipe(dest('src/css'));
}
export const fix = parallel(fixJs, fixCss);
export function build() {
return src('src/**/*.{js,css}').pipe(dest('dist'));
}
export default series(lint, build);
The rest of the file, the fix tasks and the default task, is explained in the following sections.
Running ESLint
We run lintJs. The report shows each problem with its position, severity and rule name; the summary tells how many
problems can be fixed automatically. The task fails because of the three errors, and gulp exits with status 1. The warning
did not count.
$ npx gulp lintJs --silent; echo "exit status: $?" [13:57:16] ~/Documents/prog/js/gulp-lint/src/js/app.js 2:5 error 'unused' is assigned a value but never used no-unused-vars 5:15 error Expected '===' and instead saw '==' eqeqeq 6:9 warning Unexpected console statement no-console 6:31 error Missing semicolon semi ✖ 4 problems (3 errors, 1 warning) 1 error and 0 warnings potentially fixable - see https://www.npmjs.com/package/gulp-eslint-new/v/2.6.2#autofix exit status: 1
Running Stylelint
The lintCss task reports the two problems of the stylesheet in the same way.
$ npx gulp lintCss --silent; echo "exit status: $?" src/css/style.css 3:14 ✖ Disallowed unit length-zero-no-unit 7:5 ✖ Duplicate property "color" declaration-block-no-duplicate-properties ✖ 2 problems (2 errors, 0 warnings) 2 errors potentially fixable with the "--fix" option. exit status: 1
Running both linters
The lint task runs the two tasks in parallel. When one of them fails, Gulp stops waiting for the other, and its report
may be lost: here only the report of ESLint is printed, because it failed first, and the problems of the stylesheet are not shown.
To see every problem we run the two tasks separately, as the commands above; series does not help, because it stops at the first failure too.
$ npx gulp lint --silent; echo "exit status: $?" [13:57:17] ~/Documents/prog/js/gulp-lint/src/js/app.js 2:5 error 'unused' is assigned a value but never used no-unused-vars 5:15 error Expected '===' and instead saw '==' eqeqeq 6:9 warning Unexpected console statement no-console 6:31 error Missing semicolon semi ✖ 4 problems (3 errors, 1 warning) 1 error and 0 warnings potentially fixable - see https://www.npmjs.com/package/gulp-eslint-new/v/2.6.2#autofix exit status: 1
Fixing problems automatically
Both linters can fix some problems. For ESLint we pass the fix: true option, and eslint.fix() puts
the fixed source back into the file objects; then dest writes them over the originals. The src and dest
pair is described in Gulp src and dest. The Stylelint plugin with the fix option
writes the fixed files itself. We pass an empty reporters list so that only the summary line of the plugin is printed.
export function fixJs() {
return src('src/js/**/*.js')
.pipe(eslint({ fix: true }))
.pipe(eslint.fix())
.pipe(eslint.format())
.pipe(dest('src/js'));
}
export function fixCss() {
return src('src/css/**/*.css')
.pipe(gulpStylelint({ fix: true, reporters: [] }))
.pipe(dest('src/css'));
}
After the fix task the missing semicolon is added and the stylesheet is repaired: the unit after zero and the duplicated declaration are gone.
The problems that need a decision, the unused variable and the loose comparison, remain in the report. Only fix files that are under version control,
because the task changes the sources.
$ npx gulp fix --silent
[13:57:18]
~/Documents/prog/js/gulp-lint/src/js/app.js
2:5 error 'unused' is assigned a value but never used no-unused-vars
5:15 error Expected '===' and instead saw '==' eqeqeq
6:9 warning Unexpected console statement no-console
✖ 3 problems (2 errors, 1 warning)
src/css/style.css >> fixed and overwrote
$ cat src/js/app.js
const greeting = 'Hello';
let unused = 42;
function show(value) {
if (value == null) {
console.log('nothing');
}
document.title = greeting + ' ' + value;
}
show('Gulp');
$ cat src/css/style.css
body {
color: #FFF;
margin: 0;
}
a {
color: red;
}
Failing the build
The default task runs lint and then build in series, so a failure in linting means that no file is built. We repair the two remaining problems by hand and
run the default task. The build passes, because the no-console warning does not fail the task, and
the files are written to dist.
$ sed -i '/let unused/d; s/value == null/value === null/' src/js/app.js $ npx gulp --silent; echo "exit status: $?" [13:57:19] ~/Documents/prog/js/gulp-lint/src/js/app.js 5:9 warning Unexpected console statement no-console ✖ 1 problem (0 errors, 1 warning) exit status: 0 $ ls dist css js
Source
ESLint configuration files, Stylelint configuration, gulp-eslint-new on npm, gulp-stylelint-esm on npm
In this article we have linted JavaScript with ESLint and CSS with Stylelint in Gulp 5 tasks, failed the build on errors, let the warnings pass, and fixed the simple problems automatically. See also the Gulp error handling and Gulp watch tutorials.
Author
List all Gulp tutorials.