Gulp Header

Gulp Header is a Gulp plugin that adds customizable headers to files in your build pipeline. It supports both static text headers and dynamic template-based headers using lodash template syntax or ES6 template strings, allowing for the inclusion of package metadata, build information, and custom data.

Package Information

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

Core Imports

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

For ES6 modules:

import header from 'gulp-header';

Basic Usage

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

// Add literal text header
gulp.src('./src/*.js')
  .pipe(header('/* This is a header */\n'))
  .pipe(gulp.dest('./dist/'));

// Add template-based header with data
const pkg = require('./package.json');
const banner = [
  '/**',
  ' * <%= pkg.name %> - <%= pkg.description %>',
  ' * @version v<%= pkg.version %>',
  ' * @license <%= pkg.license %>',
  ' */',
  ''
].join('\n');

gulp.src('./src/*.js')
  .pipe(header(banner, { pkg: pkg }))
  .pipe(gulp.dest('./dist/'));

Capabilities

Header Function

Main plugin function that creates a transform stream to add headers to files in the Gulp pipeline.

/**
 * Creates a Gulp transform stream that adds headers to files
 * @param {string} headerText - The header text to add (supports templates)
 * @param {Object|false} data - Template data object or false to disable templating
 * @returns {NodeJS.Transform} Transform stream for Gulp pipeline
 */
function header(headerText, data);

// Type definitions for Vinyl file objects used in templates
interface VinylFile {
  path: string;           // Full file path
  relative: string;       // Path relative to base
  base: string;          // Base directory path
  contents: Buffer | NodeJS.ReadableStream | null;
  data?: any;            // Custom data attached to file
  sourceMap?: any;       // Source map information
  isBuffer(): boolean;   // Check if contents is Buffer
  isStream(): boolean;   // Check if contents is Stream
  isDirectory(): boolean; // Check if file is directory
}

Parameters

headerText (string, optional)

• Default: '' (empty string)
• The template text to be added as header to files
• Supports plain text strings
• Supports lodash template syntax: <%= variable %> (e.g., <%= pkg.name %>)
• Supports ES6 template string syntax: ${variable} (e.g., ${pkg.version})

data (Object|false, optional)

• Default: {} (empty object)
• Template data object used to populate template variables
• When set to false, disables template processing and treats headerText as literal string
• Merged with built-in variables (file, filename) and any custom file.data properties
• Data precedence: passed data overrides file.data, which overrides built-in variables

Built-in Template Variables

The following variables are automatically available in templates:

• file: The current Vinyl file object being processed (includes properties like file.path, file.relative, file.base)
• filename: Base name of the file being processed (from path.basename(file.path))
• file.data: Any custom data properties attached to the Vinyl file object

Template Syntax Support

Gulp Header supports two template syntax formats:

• Lodash template syntax: <%= variable %> - Standard lodash template format
• ES6 template string syntax: ${variable} - ES6-style variable interpolation

Return Value

Returns a Node.js transform stream compatible with Gulp's streaming system that:

• Processes Vinyl file objects
• Adds header text to file contents
• Preserves source maps when present
• Handles both buffer and stream file types
• Passes through directories and invalid files unchanged

Usage Examples

Literal Text Header

gulp.src('./src/*.js')
  .pipe(header('/* Copyright 2023 My Company */\n'))
  .pipe(gulp.dest('./dist/'));

Template with Package Data

const pkg = require('./package.json');
const banner = [
  '/**',
  ' * <%= pkg.name %> v<%= pkg.version %>',
  ' * <%= pkg.description %>',
  ' * @author <%= pkg.author %>',
  ' * @license <%= pkg.license %>',
  ' */',
  ''
].join('\n');

gulp.src('./src/*.js')
  .pipe(header(banner, { pkg: pkg }))
  .pipe(gulp.dest('./dist/'));

ES6 Template String Syntax

// ES6 template syntax with custom data
gulp.src('./src/*.js')
  .pipe(header('/* Built on ${date} by ${author} */\n', { 
    date: new Date().toISOString(),
    author: 'Build System'
  }))
  .pipe(gulp.dest('./dist/'));

// ES6 syntax with file properties
gulp.src('./src/*.js')
  .pipe(header('/* Processing: ${file.relative} */\n'))
  .pipe(gulp.dest('./dist/'));

Reading Header from File

const fs = require('fs');
const headerText = fs.readFileSync('header.txt', 'utf8');

gulp.src('./src/*.js')
  .pipe(header(headerText, { version: '1.0.0' }))
  .pipe(gulp.dest('./dist/'));

Disable Template Processing

// Use false as second parameter to treat header as literal text
gulp.src('./src/*.js')
  .pipe(header('/* Literal text with <%= symbols %> */\n', false))
  .pipe(gulp.dest('./dist/'));

Using Built-in Variables

// Using filename and file properties
gulp.src('./src/*.js')
  .pipe(header('/* File: <%= filename %> - Path: <%= file.relative %> - Generated: <%= date %> */\n', {
    date: new Date().toLocaleDateString()
  }))
  .pipe(gulp.dest('./dist/'));

// Accessing file data properties
gulp.src('./src/*.js')
  .pipe(header('/* License: <%= license %> - Version: <%= version %> */\n'))
  .pipe(gulp.dest('./dist/'));
// Note: This assumes files have data.license and data.version properties

With Source Maps (CoffeeScript Example)

const sourcemaps = require('gulp-sourcemaps');
const coffee = require('gulp-coffee');

gulp.src('./src/*.coffee')
  .pipe(header(banner, { pkg: pkg }))  // Add header before sourcemaps
  .pipe(sourcemaps.init())
  .pipe(coffee({ bare: true }))
  .pipe(sourcemaps.write('.'))
  .pipe(gulp.dest('./dist/'));

File Type Support

The plugin handles different file types appropriately:

• Buffer files: Directly concatenates header with file contents using source map-aware concatenation
• Stream files: Creates a new stream that outputs the header first, then pipes the original file stream
• String inputs: Simple string concatenation (legacy support for direct string processing)
• Directories: Passed through unchanged (skipped without processing)
• Invalid files: Passed through unchanged (files that fail validation are skipped)

Error Handling and File Validation

The plugin includes built-in error handling and file validation:

• File validation: Uses isExistingFile() to check if a file is valid for processing
• Stream error propagation: Stream errors are properly propagated through the pipeline
• Template errors: Invalid template syntax or missing variables will cause processing to fail
• Graceful skipping: Non-file objects (directories, null files) are passed through without error

Source Map Support

Gulp Header automatically preserves and updates source map information when present, ensuring debugging capabilities are maintained in the build output. Source maps are handled through the concat-with-sourcemaps dependency.

Dependencies

The plugin relies on these key dependencies for its functionality:

• concat-with-sourcemaps: Handles source map-aware file concatenation
• lodash.template: Processes template strings with variable substitution
• through2: Creates the transform stream for Gulp integration
• map-stream: Provides streaming utilities (legacy dependency)