or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-gulp-imagemin

Minify PNG, JPEG, GIF and SVG images with imagemin in Gulp pipelines

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/gulp-imagemin@9.1.x

To install, run

npx @tessl/cli install tessl/npm-gulp-imagemin@9.1.0

gulp-imagemin

gulp-imagemin is a Gulp plugin that provides automated image minification for PNG, JPEG, GIF, and SVG files. It integrates seamlessly with Gulp build pipelines to optimize images during the build process, offering configurable compression settings through various imagemin plugins with significant file size reduction while maintaining visual quality.

Package Information

Package Name: gulp-imagemin
Package Type: npm
Language: JavaScript (ES modules)
Installation: npm install --save-dev gulp-imagemin
Repository: https://github.com/sindresorhus/gulp-imagemin
License: MIT

Core Imports

import imagemin from 'gulp-imagemin';

For importing with plugin helpers:

import imagemin, { gifsicle, mozjpeg, optipng, svgo } from 'gulp-imagemin';

Basic Usage

import gulp from 'gulp';
import imagemin from 'gulp-imagemin';

export default () => (
  gulp.src('src/images/*')
    .pipe(imagemin())
    .pipe(gulp.dest('dist/images'))
);

Architecture

gulp-imagemin is built around several key components:

Main Plugin Function: Core gulp plugin that processes image files through the imagemin library
Plugin Helpers: Convenience functions for accessing imagemin optimization plugins
Default Plugins: Pre-configured plugins for common image formats (gifsicle, mozjpeg, optipng, svgo)
Stream Processing: Transforms image files in Gulp streams with compression and logging
Lazy Loading: Dynamically loads imagemin plugins to reduce startup time and handle optional dependencies

Capabilities

Main Plugin Function

Core gulp plugin function for image minification with configurable plugins and options.

/**
 * Creates a gulp transform stream for image minification
 * @param plugins - Array of imagemin plugins (optional, defaults to [gifsicle(), mozjpeg(), optipng(), svgo()])
 * @param options - Configuration options for the plugin
 * @returns Gulp transform stream
 */
function imagemin(plugins?: Array<Function>, options?: object): NodeJS.Transform;

/**
 * Alternative signature where first parameter is options object
 * @param options - Configuration options for the plugin
 * @returns Gulp transform stream
 */
function imagemin(options?: object): NodeJS.Transform;

// Options object properties
interface Options {
  /** Enable detailed logging for each processed image (default: false, or true if --verbose CLI flag is present) */
  verbose?: boolean;
  /** Disable summary logging of minification results (default: false, or true if --silent CLI flag is present) */
  silent?: boolean;
}

Usage Examples:

import gulp from 'gulp';
import imagemin from 'gulp-imagemin';

// Basic usage with default plugins
gulp.src('src/images/*')
  .pipe(imagemin())
  .pipe(gulp.dest('dist/images'));

// With verbose logging (also automatically enabled with --verbose CLI flag)
gulp.src('src/images/*')
  .pipe(imagemin({ verbose: true }))
  .pipe(gulp.dest('dist/images'));

// With silent mode (also automatically enabled with --silent CLI flag)
gulp.src('src/images/*')
  .pipe(imagemin({ silent: true }))
  .pipe(gulp.dest('dist/images'));

Plugin Helper Functions

Convenience functions for creating imagemin plugin instances with custom configurations.

/**
 * Plugin helper that creates an async function to load and configure the gifsicle imagemin plugin
 * @param options - Options to pass to the imagemin-gifsicle plugin
 * @returns Function that loads and returns the configured plugin
 */
const gifsicle: (...arguments_: any[]) => Promise<Function>;

/**
 * Plugin helper that creates an async function to load and configure the mozjpeg imagemin plugin
 * @param options - Options to pass to the imagemin-mozjpeg plugin
 * @returns Function that loads and returns the configured plugin
 */
const mozjpeg: (...arguments_: any[]) => Promise<Function>;

/**
 * Plugin helper that creates an async function to load and configure the optipng imagemin plugin
 * @param options - Options to pass to the imagemin-optipng plugin
 * @returns Function that loads and returns the configured plugin
 */
const optipng: (...arguments_: any[]) => Promise<Function>;

/**
 * Plugin helper that creates an async function to load and configure the svgo imagemin plugin
 * @param options - Options to pass to the imagemin-svgo plugin
 * @returns Function that loads and returns the configured plugin
 */
const svgo: (...arguments_: any[]) => Promise<Function>;

Usage Examples:

import imagemin, { gifsicle, mozjpeg, optipng, svgo } from 'gulp-imagemin';

// Custom plugin configuration
gulp.src('src/images/*')
  .pipe(imagemin([
    gifsicle({ interlaced: true }),
    mozjpeg({ quality: 75, progressive: true }),
    optipng({ optimizationLevel: 5 }),
    svgo({
      plugins: [
        { name: 'removeViewBox', active: true },
        { name: 'cleanupIDs', active: false }
      ]
    })
  ]))
  .pipe(gulp.dest('dist/images'));

// Mixed approach: custom plugins with options
gulp.src('src/images/*')
  .pipe(imagemin([
    svgo({
      plugins: [
        { name: 'removeViewBox', active: true }
      ]
    })
  ], {
    verbose: true
  }))
  .pipe(gulp.dest('dist/images'));

Supported File Types

The plugin processes files with the following extensions (case-insensitive):

// Valid extensions defined in source code
const validExtensions = ['.jpg', '.jpeg', '.png', '.gif', '.svg'];

JPEG: .jpg, .jpeg files (processed with mozjpeg by default)
PNG: .png files (processed with optipng by default)
GIF: .gif files (processed with gifsicle by default)
SVG: .svg files (processed with svgo by default)

Files with unsupported extensions are passed through unchanged. In verbose mode, skipped files are logged with a message like: "gulp-imagemin: Skipping unsupported image filename.bmp".

Logging and Output

The plugin provides several levels of output:

Default: Summary of total files processed and bytes saved
Verbose: Individual file processing results with size savings
Silent: No output at all

Example verbose output:

gulp-imagemin: ✔ image1.png (already optimized)
gulp-imagemin: ✔ image2.png (saved 91 B - 0.4%)
gulp-imagemin: Minified 2 images (saved 91 B - 0.2%)

All log messages are prefixed with the plugin name constant:

const PLUGIN_NAME = 'gulp-imagemin';

Error Handling

Plugin Loading Failures: If default plugins fail to load, they are skipped with console.log warnings (format: "gulp-imagemin: Could not load default plugin \pluginName`"`)
Unsupported Files: Files with unsupported extensions are passed through unchanged with their contents set to the original buffer
Processing Errors: Individual file processing errors don't break the entire stream due to gulp-plugin-extras error handling

Command Line Integration

The plugin automatically detects command-line flags to configure logging behavior:

// Plugin automatically detects these CLI flags
const options = {
  silent: process.argv.includes('--silent'),   // Disables summary logging
  verbose: process.argv.includes('--verbose'), // Enables detailed per-file logging
  ...userOptions, // User-provided options override CLI flags
};

This allows you to control logging from your build scripts:

# Enable verbose logging for all imagemin operations
gulp build --verbose

# Disable all imagemin logging
gulp build --silent

Default Plugin Behavior

When no plugins are specified, gulp-imagemin uses these default configurations:

gifsicle(): GIF optimization with default settings
mozjpeg(): JPEG optimization with default quality settings
optipng(): PNG optimization with default compression level
svgo(): SVG optimization with default plugin configuration

These defaults provide good compression for most use cases while maintaining reasonable processing speed.

Integration with Gulp

gulp-imagemin integrates seamlessly with Gulp workflows:

import gulp from 'gulp';
import imagemin, { mozjpeg, optipng } from 'gulp-imagemin';

// Watch task for development
export const watchImages = () => {
  return gulp.watch('src/images/**/*', gulp.series('images'));
};

// Production build task
export const images = () => {
  return gulp.src('src/images/**/*')
    .pipe(imagemin([
      mozjpeg({ quality: 80 }),
      optipng({ optimizationLevel: 7 })
    ], { verbose: true }))
    .pipe(gulp.dest('dist/images'));
};

Performance Considerations

Plugin Loading: Plugins are loaded lazily on first use to improve startup time
Optional Dependencies: Default plugins are optional dependencies, allowing selective installation
Stream Processing: Processes files individually without loading entire datasets into memory
Parallel Processing: Can be combined with gulp-newer or similar plugins to process only changed files