or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-gulp-jshint

JSHint plugin for gulp that integrates JavaScript linting into build workflows

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/gulp-jshint@2.1.x

To install, run

npx @tessl/cli install tessl/npm-gulp-jshint@2.1.0

index.mddocs/

Gulp JSHint

Gulp JSHint is a Gulp plugin that integrates JSHint JavaScript linting into build workflows. It enables developers to automatically check JavaScript code quality and style compliance as part of their build process, supporting various JSHint configuration options, custom reporters for output formatting, and the ability to fail builds when linting errors are detected.

Package Information

  • Package Name: gulp-jshint
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install jshint gulp-jshint --save-dev

Note: As of version 2.0, JSHint must be installed as a peer dependency alongside gulp-jshint.

Core Imports

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

For ES modules:

import jshint from 'gulp-jshint';

Basic Usage

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

gulp.task('lint', function() {
  return gulp.src('./lib/*.js')
    .pipe(jshint())
    .pipe(jshint.reporter('default'))
    .pipe(jshint.reporter('fail'));
});

Architecture

Gulp JSHint follows a modular architecture built around several key components:

  • Main Plugin Function: Factory function that creates the linting transform stream
  • Reporter System: Pluggable reporting interface supporting JSHint built-in reporters and custom reporters
  • Configuration Loading: Automatic discovery and loading of .jshintrc and .jshintignore files
  • File Processing: Stream-based file processing with support for JavaScript extraction from HTML
  • Error Handling: Comprehensive error reporting and build failure mechanisms

Capabilities

Main Linting Function

Creates a transform stream that lints JavaScript files using JSHint.

/**
 * Main gulp-jshint plugin function that creates a linting transform stream
 * @param {Object} [opt] - JSHint configuration options
 * @param {boolean} [opt.lookup=true] - Whether to lookup .jshintrc files
 * @param {string|function} [opt.linter='jshint'] - Custom linter module or function
 * @returns {Stream} Transform stream for gulp pipeline
 */
function jshint(opt);

Usage Examples:

// Basic usage with default options
gulp.src('src/*.js')
  .pipe(jshint())

// With custom JSHint options
gulp.src('src/*.js')
  .pipe(jshint({
    esversion: 6,
    node: true,
    strict: true
  }))

// Disable .jshintrc lookup
gulp.src('src/*.js')
  .pipe(jshint({ lookup: false }))

// Use custom linter
gulp.src('src/*.js')
  .pipe(jshint({ linter: 'jsxhint' }))

Reporter Function

Creates a reporter stream for displaying JSHint results.

/**
 * Creates a reporter stream for displaying JSHint results
 * @param {string|function|Object} [reporter='default'] - Reporter type or function
 * @param {Object} [reporterCfg] - Reporter configuration options
 * @returns {Stream} Transform stream for reporting
 */
jshint.reporter(reporter, reporterCfg);

Usage Examples:

// Built-in JSHint reporter
.pipe(jshint.reporter('default'))

// External reporter module
.pipe(jshint.reporter('jshint-stylish'))

// Custom reporter function
.pipe(jshint.reporter(function(results, data, opts) {
  // Custom reporting logic
}))

// Reporter with configuration
.pipe(jshint.reporter('default', { verbose: true }))

Fail Reporter

Creates a reporter that fails the build when JSHint errors are detected.

/**
 * Creates a fail reporter that emits errors when linting fails
 * @param {Object} [opts] - Fail reporter options
 * @param {boolean} [opts.buffer=true] - Whether to buffer files for downstream
 * @param {boolean} [opts.ignoreWarning=false] - Whether to ignore warning-level messages
 * @param {boolean} [opts.ignoreInfo=false] - Whether to ignore info-level messages
 * @returns {Stream} Transform stream that emits errors on failures
 */
jshint.reporter('fail', opts);

Fail Reporter Function

Direct access to the fail reporter function (alias for jshint.reporter('fail')).

/**
 * Direct fail reporter function (alias for jshint.reporter('fail'))
 * @param {Object} [opts] - Fail reporter options
 * @param {boolean} [opts.buffer=true] - Whether to buffer files for downstream
 * @param {boolean} [opts.ignoreWarning=false] - Whether to ignore warning-level messages  
 * @param {boolean} [opts.ignoreInfo=false] - Whether to ignore info-level messages
 * @returns {Stream} Transform stream that emits errors on failures
 */
jshint.failReporter(opts);

Usage Examples:

// Fail on any errors
.pipe(jshint.reporter('fail'))

// Ignore warnings when failing
.pipe(jshint.reporter('fail', { ignoreWarning: true }))

// Don't buffer files (pass through immediately)
.pipe(jshint.reporter('fail', { buffer: false }))

// Using the direct failReporter function
.pipe(jshint.failReporter())

// Direct failReporter with options
.pipe(jshint.failReporter({ ignoreWarning: true }))

Load Reporter Function

Utility function for loading and validating reporter functions from various sources.

/**
 * Loads reporter from various sources (functions, objects, modules, JSHint built-ins)
 * @param {string|function|Object} reporter - Reporter specification
 * @returns {function|undefined} Reporter function or undefined if invalid
 */
jshint.loadReporter(reporter);

Usage Examples:

// Load JSHint built-in reporter
const reporter = jshint.loadReporter('default');

// Load external module
const reporter = jshint.loadReporter('jshint-stylish');

// Validate function reporter
const reporter = jshint.loadReporter(myCustomReporter);

Extract Function

Creates a stream for extracting JavaScript from HTML files before linting.

/**
 * Creates stream for extracting JavaScript from HTML files
 * @param {string} [when='auto'] - Extraction mode: 'auto', 'always', or 'never'
 * @returns {Stream} Transform stream for JavaScript extraction
 */
jshint.extract(when);

Usage Examples:

// Extract from HTML files with auto detection
gulp.src('src/*.html')
  .pipe(jshint.extract('auto'))
  .pipe(jshint())
  .pipe(jshint.reporter('default'))

// Always extract JavaScript
gulp.src('src/*.html')
  .pipe(jshint.extract('always'))
  .pipe(jshint())

// Never extract (treat as plain text)
gulp.src('src/*.html')
  .pipe(jshint.extract('never'))
  .pipe(jshint())

File Object Properties

After processing with gulp-jshint, file objects receive additional properties:

/**
 * Properties added to vinyl file objects by gulp-jshint
 */
interface FileJSHintProperties {
  /** JSHint results and metadata */
  jshint: {
    /** Whether linting passed without errors */
    success: boolean;
    /** Array of JSHint error objects (only present when success is false) */
    results?: Array<{
      file: string;
      error: {
        id: string;
        code: string;
        reason: string;
        evidence: string;
        line: number;
        character: number;
      };
    }>;
    /** JSHint data about complexity, globals, etc. (only present when success is false) */
    data?: Array<{
      file: string;
      functions: Object[];
      options: Object;
      errors: Object[];
      implieds: Object[];
      globals: Object[];
    }>;
    /** Effective JSHint options used (only present when success is false) */
    opt?: Object;
    /** Extracted JavaScript (when using extract) */
    extracted?: string;
    /** Whether file was ignored */
    ignored?: boolean;
  };
}

Configuration Options

Main Plugin Options

/**
 * Configuration options for the main jshint function
 */
interface JSHintOptions {
  /** Whether to lookup .jshintrc configuration files */
  lookup?: boolean;
  /** Custom linter module name or function */
  linter?: string | function;
  /** JSHint configuration options */
  [jshintOption: string]: any;
}

JSHint Configuration

All standard JSHint options are supported. Common options include:

{
  esversion: 6,        // ECMAScript version
  node: true,          // Node.js environment
  browser: true,       // Browser environment  
  strict: true,        // Require strict mode
  undef: true,         // Prohibit undefined variables
  unused: true,        // Prohibit unused variables
  globals: {           // Global variables
    myGlobal: false
  }
}

Reporter Configuration

/**
 * Configuration options for reporters
 */
interface ReporterConfig {
  /** Enable verbose output (for compatible reporters) */
  verbose?: boolean;
  /** Custom reporter-specific options */
  [option: string]: any;
}

Error Handling

The plugin handles several types of errors:

  • JSHint Errors: Syntax and style violations reported by JSHint
  • Configuration Errors: Invalid .jshintrc files or plugin options
  • File Processing Errors: Issues reading or processing files
  • Reporter Errors: Problems with custom reporter functions

When using the fail reporter, the plugin will emit a PluginError that stops the gulp pipeline:

// Error object structure
{
  plugin: 'gulp-jshint',
  message: 'JSHint failed for: file1.js, file2.js',
  showStack: false
}

Custom Reporters

You can create custom reporters by implementing a function that receives JSHint results:

function customReporter(results, data, opts) {
  results.forEach(function(result) {
    if (result.error) {
      console.log(`${result.file}: line ${result.error.line}, ${result.error.reason}`);
    }
  });
}

// Usage
.pipe(jshint.reporter(customReporter))