gulp-pug-linter

1.5.0 verified Fri May 01 auth: no javascript maintenance

Gulp plugin for linting Pug (formerly Jade) template files using pug-lint. Stable version 1.5.0 (2021-02-06), no longer actively maintained (last release 2021). It wraps pug-lint with Gulp streams, supporting custom reporters, fail-after-error mode, and silence-on-success. Key differentiators: no-frills wrapper that works with existing pug-lint configuration files (.pug-lintrc, .pug-lint.json, package.json). Requires Node >=10.x. Alternatives: direct pug-lint CLI or other Gulp linters.

Common errors

error Error: Cannot find module 'gulp-pug-linter' ↓

cause Package not installed or installed as devDependency but not in node_modules

fix

Run 'npm install gulp-pug-linter --save-dev'

error TypeError: pugLinter is not a function ↓

cause Using import statement in CommonJS environment or wrong import style

fix

Use 'const pugLinter = require('gulp-pug-linter');' instead of import or destructuring.

error Error: Couldn't find pug-lint configuration file. See pug-lint's documentation for more info. ↓

cause Missing .pug-lintrc or equivalent configuration file in project root

fix

Create a .pug-lintrc.json file with pug-lint rules, e.g., { "extends": "clockwork" }

Warnings

breaking Node.js engine requirement >=10.x (dropped support for 8.x and below) ↓

fix Upgrade Node.js to version 10 or higher.

breaking API changed in v1.0.0: new options object format (reporter, failAfterError) replaces old separate reporter() method ↓

fix Use options object, e.g., pugLinter({ reporter: 'default', failAfterError: true }).

deprecated Separate reporter() stream handler (including 'fail' flag) deprecated since v0.7.0 and removed in v1.0.0 ↓

fix Migrate to new options object API: pugLinter({ reporter: 'default', failAfterError: true }).

gotcha If no reporter is specified and failAfterError is true, build fails without displaying lint errors ↓

fix Always provide a reporter (e.g., 'default') when using failAfterError.

gotcha Invalid reporter value falls back to 'default' reporter silently (with warning printed to console) ↓

fix Ensure reporter value is valid: 'default', a string name, or a reporter function.

Install

npm install gulp-pug-linter

yarn add gulp-pug-linter

pnpm add gulp-pug-linter

Imports

default

wrong

import pugLinter from 'gulp-pug-linter';

correct

const pugLinter = require('gulp-pug-linter');

Package does not ship ESM; CommonJS only. Use require().

pugLinter

wrong

const { pugLinter } = require('gulp-pug-linter');

correct

const pugLinter = require('gulp-pug-linter');

Default export, not named export. Use require() directly.

gulp.task

wrong

gulp.task('lint', () => pugLinter.pipe())

correct

gulp.task('lint', () => gulp.src().pipe(pugLinter()))

Must pipe through a Gulp stream, not call pugLinter standalone.

Quickstart

Gulp task to lint all .pug files using default reporter and fail on errors.

const gulp = require('gulp');
const pugLinter = require('gulp-pug-linter');

gulp.task('lint:pug', () =>
  gulp
    .src('./**/*.pug')
    .pipe(pugLinter({ reporter: 'default', failAfterError: true }))
);