gulp-clean

A Gulp plugin for removing files and folders safely as part of build workflows. It provides a stream-based API that integrates with Gulp's file pipeline, allowing developers to clean directories and files before or after build processes.

Note: This package has been deprecated in favor of the official Gulp recipe for deleting files and folders.

Package Information

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

Core Imports

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

Basic Usage

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

// Basic file cleaning
gulp.task('clean', function () {
  return gulp.src('dist/*', { read: false })
    .pipe(clean());
});

// Clean with force option (allows deletion outside CWD)
gulp.task('clean-all', function () {
  return gulp.src('../temp/*', { read: false })
    .pipe(clean({ force: true }));
});

Architecture

gulp-clean is built around Gulp's streaming architecture:

• Transform Stream: Returns a Node.js Transform stream that processes Vinyl file objects
• Safety Layer: Prevents accidental deletion of files outside the current working directory
• Error Handling: Emits proper error events for failed operations
• Cross-Platform: Uses rimraf internally for reliable file deletion across operating systems

Capabilities

Clean Function

Creates a Transform stream for deleting files and folders from the filesystem.

/**
 * Creates a Transform stream for deleting files and folders
 * @param {Object} [options] - Configuration options
 * @param {boolean} [options.force=false] - Allow deletion of files outside current working directory
 * @returns {Object} - Transform stream for use in Gulp pipelines
 */
function clean(options)

Parameters:

• options (optional): Configuration object
  • force (boolean): When true, allows deletion of files outside the current working directory and the current working directory itself. Default: false

Returns:

• Object: A Node.js Transform stream (through2 object stream) that processes Vinyl file objects

Behavior:

• Accepts Vinyl file objects through the Transform stream
• Uses rimraf for cross-platform file deletion
• Passes files through the stream after processing deletion
• Emits 'error' events for failed operations
• Validates file paths using path.relative() to determine if files are outside CWD
• Prevents deletion of current working directory (when relative path is empty, unless force: true)
• Prevents deletion of files outside current working directory (when relative path starts with '..', unless force: true)

Usage Examples:

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

// Clean build directory
gulp.task('clean:build', function () {
  return gulp.src('build/**/*', { read: false })
    .pipe(clean());
});

// Clean with logging
gulp.task('clean:temp', function () {
  return gulp.src('temp/**/*', { read: false })
    .pipe(clean())
    .on('error', function(err) {
      console.error('Clean failed:', err.message);
    });
});

// Force clean files outside CWD (dangerous - use with caution)
gulp.task('clean:external', function () {
  return gulp.src('../external-temp/*', { read: false })
    .pipe(clean({ force: true }));
});

// Clean as part of build pipeline
gulp.task('build', gulp.series('clean:build', function() {
  return gulp.src('src/**/*')
    .pipe(/* other build steps */)
    .pipe(gulp.dest('build/'));
}));

Error Handling

The plugin emits error events in the following situations:

• Cannot delete current working directory: When attempting to delete the CWD without force: true
• Cannot delete files outside CWD: When attempting to delete files outside the current working directory without force: true
• File system errors: When rimraf encounters errors during deletion (permissions, file locks, etc.)

All errors are emitted as PluginError instances with descriptive messages:

// Exact error messages from source code:
// "Cannot delete current working directory. (" + filepath + "). Use option force."
// "Cannot delete files outside the current working directory. (" + filepath + "). Use option force."
// "Unable to delete \"" + filepath + "\" file (" + error.message + ")."

Safety Features

• Path validation: Prevents deletion of files outside the current working directory unless explicitly forced
• CWD protection: Prevents deletion of the current working directory unless explicitly forced
• Error propagation: Properly emits errors instead of silently failing
• File passthrough: Files are passed through the stream even when deletion fails, allowing the pipeline to continue

Integration Notes

• Designed specifically for Gulp build workflows
• Works with Gulp's src() and dest() methods
• Compatible with Gulp 3.x and 4.x task systems
• Should be used with { read: false } option in gulp.src() for better performance when only deleting files
• Can be combined with other Gulp plugins in streaming pipelines

Utilities Module

The plugin includes a utilities module that re-exports common dependencies for internal use.

/**
 * Utility exports for internal plugin operations
 */
const utils = {
  PluginError: require('plugin-error'),
  log: require('fancy-log'),
  File: require('vinyl')
}

Note: The utils module is primarily for internal use and is not part of the main public API.

Dependencies

The plugin relies on the following key dependencies:

• rimraf: Cross-platform file deletion (v2.6.2)
• through2: Transform stream creation (v2.0.3)
• plugin-error: Standardized error handling for Gulp plugins (v0.1.2)
• fancy-log: Logging functionality (v1.3.2)
• vinyl: File object handling (Gulp's file format) (v2.1.0)