imagemin

imagemin is a Node.js library that provides seamless image minification through a plugin-based architecture. It supports multiple image formats (JPEG, PNG, GIF, SVG, WebP) and offers both file-based and buffer-based processing with glob pattern support for batch operations.

Package Information

• Package Name: imagemin
• Package Type: npm
• Language: JavaScript (ES Modules)
• Installation: npm install imagemin

Core Imports

import imagemin from 'imagemin';

Note: This package only supports ES modules and requires Node.js 18+. CommonJS import is not supported.

Basic Usage

import imagemin from 'imagemin';
import imageminJpegtran from 'imagemin-jpegtran';
import imageminPngquant from 'imagemin-pngquant';

// Process image files with plugins
const files = await imagemin(['images/*.{jpg,png}'], {
  destination: 'build/images',
  plugins: [
    imageminJpegtran(),
    imageminPngquant({
      quality: [0.6, 0.8]
    })
  ]
});

console.log(files);
// Returns: [{data: Uint8Array, sourcePath: string, destinationPath: string}, ...]

// Process image buffer directly
import fs from 'node:fs/promises';
const buffer = await fs.readFile('image.jpg');
const optimizedBuffer = await imagemin.buffer(buffer, {
  plugins: [imageminJpegtran()]
});

Architecture

imagemin follows a plugin-based architecture with these key components:

• Main Function: Processes files or glob patterns, handles file I/O and directory creation
• Buffer Processing: Direct binary data processing without file system operations
• Plugin System: Chainable image optimization plugins using p-pipe for sequential processing
• File Type Detection: Automatic format detection and extension handling
• Glob Support: Pattern matching for batch file processing using globby

Capabilities

File-based Image Processing

The main imagemin function processes image files from the filesystem using glob patterns.

/**
 * Minify images from file paths or glob patterns
 * @param {string[]} input - Array of file paths or glob patterns to process
 * @param {Object} [options] - Processing options including destination and plugins
 * @param {string} [options.destination] - Output directory path
 * @param {Function[]} [options.plugins] - Array of imagemin plugins to apply
 * @param {boolean} [options.glob=true] - Enable/disable glob pattern matching
 * @returns {Promise<Array<Object>>} Promise resolving to array of processing results
 */
function imagemin(input, options);

Parameters:

• input: Array of file paths or glob patterns (e.g., ['images/*.jpg', 'photos/*.png'])
• options.destination: Optional output directory. If not provided, files are not written to disk
• options.plugins: Array of imagemin plugins to apply sequentially
• options.glob: Enable/disable glob pattern matching (default: true)

Returns: Array of objects with the following properties:

• data (Uint8Array): Optimized image data
• sourcePath (string): Original file path
• destinationPath (string|undefined): Output file path (undefined if no destination specified)

Usage Examples:

// Basic file processing without saving
const results = await imagemin(['src/images/*.jpg']);

// Process and save to destination
const files = await imagemin(['src/images/*.{jpg,png}'], {
  destination: 'dist/images',
  plugins: [imageminJpegtran(), imageminPngquant()]
});

// Disable glob patterns for exact file paths
const exactFiles = await imagemin(['photo1.jpg', 'photo2.png'], {
  glob: false,
  plugins: [imageminJpegtran()]
});

Buffer-based Image Processing

Process image data directly from memory without filesystem operations.

/**
 * Minify image data from a buffer
 * @param {Uint8Array} data - Image data as Uint8Array
 * @param {Object} [options] - Processing options with plugins
 * @param {Function[]} [options.plugins] - Array of imagemin plugins to apply
 * @returns {Promise<Uint8Array>} Promise resolving to optimized image data
 */
imagemin.buffer(data, options);

Parameters:

• data (Uint8Array): Image data as Uint8Array (validated at runtime)
• options.plugins (Function[]): Array of imagemin plugins to apply sequentially

Returns: Optimized image data as Uint8Array

Usage Examples:

import fs from 'node:fs/promises';

// Process buffer from file
const buffer = await fs.readFile('image.jpg');
const optimized = await imagemin.buffer(buffer, {
  plugins: [imageminJpegtran()]
});

// Process buffer from HTTP response
const response = await fetch('https://example.com/image.jpg');
const imageBuffer = new Uint8Array(await response.arrayBuffer());
const result = await imagemin.buffer(imageBuffer, {
  plugins: [imageminWebp()]
});

Plugin System

imagemin uses a plugin-based architecture where plugins are functions that process image data. Plugins are applied sequentially using p-pipe.

Plugin Interface

/**
 * Plugin function signature - all imagemin plugins follow this interface
 * @param {Uint8Array|Buffer} buffer - Image data to process
 * @returns {Promise<Uint8Array|Buffer>} Processed image data
 */
function imageminPlugin(buffer);

Common Plugins

Popular imagemin plugins for different formats:

• imagemin-jpegtran: Lossless JPEG optimization
• imagemin-mozjpeg: Lossy JPEG compression with quality control
• imagemin-pngquant: PNG compression with quality settings
• imagemin-optipng: Lossless PNG optimization
• imagemin-svgo: SVG optimization and minification
• imagemin-webp: WebP conversion and optimization
• imagemin-gif2webp: GIF to WebP conversion

Error Handling

imagemin throws errors in several scenarios:

• Browser Environment: Throws error when run in browser (not supported)
• Invalid Input Types: Validates input arrays and Uint8Array buffers
• File Processing Errors: Plugin-specific errors (e.g., corrupt image data)
• File System Errors: Directory creation or file write failures

Error Examples:

// Browser environment error
if (typeof window !== 'undefined') {
  // Throws: "This package does not work in the browser."
}

// Type validation errors
await imagemin('not-an-array'); // Throws type error
await imagemin.buffer('not-a-buffer'); // Throws Uint8Array validation error

// Plugin processing errors
try {
  await imagemin(['corrupt-image.jpg'], {
    plugins: [imageminJpegtran()]
  });
} catch (error) {
  console.log(error.message); // "Error occurred when handling file: ..."
}

Special Behaviors

File Extension Handling

imagemin automatically handles file extension changes based on output format:

• WebP Conversion: Automatically changes extension to .webp when using WebP plugins
• Format Detection: Uses file-type library to detect actual format from buffer data
• Extension Fallback: Falls back to original file extension if format detection fails

Junk File Filtering

Automatically filters out system files:

• .DS_Store (macOS)
• Thumbs.db (Windows)
• Other junk files detected by the junk library

Dimension Validation

Skips processing of images with invalid dimensions (0x0 pixels) to handle corrupted files gracefully.

Path Handling

• Unix Path Conversion: Converts Windows path separators to Unix format internally
• Glob Pattern Support: Full globby pattern support including ** for recursive matching
• Directory Creation: Automatically creates output directories as needed