image-minimizer-webpack-plugin

5.0.0 verified Sat Apr 25 auth: no javascript

Webpack loader and plugin to optimize (compress) images using imagemin, sharp, or svgo. Current stable version is 5.0.0 (released 2026-03-03), with a release cadence of major versions approximately yearly. It supports multiple backends for image optimization: imagemin (traditional), sharp (high-performance), svgo (for SVGs), and the deprecated squoosh. Key differentiators include integration as both a loader and plugin, support for generation of alternative formats (webp, avif), and filtering per minimizer. It has shipped TypeScript types and requires Node.js >=20.9.0 and webpack ^5.1.0.

Common errors

error Error: Cannot find module 'imagemin' ↓

cause imagemin or its plugins are not installed.

fix

npm install imagemin imagemin-jpegtran imagemin-optipng (or other plugins)

error TypeError: ImageMinimizerPlugin is not a constructor ↓

cause Using default import incorrectly (e.g., import * as IM from '...') or using wrong require.

fix

Use default import: import ImageMinimizerPlugin from 'image-minimizer-webpack-plugin'

error ValidationError: Invalid options object. Options should be an object. ↓

cause Passing minimizer or generator options incorrectly (e.g., array instead of object).

fix

Ensure minimizer is an object with implementation and options keys.

Warnings

breaking Minimum supported Node.js version is 20.9.0. ↓

fix Upgrade Node.js to >=20.9.0 or stay on v4.x.

breaking Minimum supported Node.js version is 18.12.0. ↓

fix Upgrade Node.js to >=18.12.0 or stay on v3.x.

deprecated squoosh optimizer has been deprecated. ↓

fix Use sharp or imagemin instead.

gotcha Concurrency default value changed to avoid CPU overload; may affect performance tuning. ↓

fix Explicitly set concurrency if defaults are not optimal.

gotcha When using filesystem cache, plugin may crash if cache is corrupted. ↓

fix Upgrade to >=4.1.4 or clear cache.

Install

npm install image-minimizer-webpack-plugin

yarn add image-minimizer-webpack-plugin

pnpm add image-minimizer-webpack-plugin

Imports

ImageMinimizerPlugin

wrong

const ImageMinimizerPlugin = require('image-minimizer-webpack-plugin')

correct

import ImageMinimizerPlugin from 'image-minimizer-webpack-plugin'

Default export is the plugin class. CommonJS require works in Node.js, but ESM is preferred.

imageminNormalizeConfig
```
import { imageminNormalizeConfig } from 'image-minimizer-webpack-plugin'
```
Named export available since v4; used to normalize config for custom integrations.
type ImageMinimizerPluginOptions
```
import type { ImageMinimizerPluginOptions } from 'image-minimizer-webpack-plugin'
```
Type import for TypeScript users; requires named export.

Quickstart

Basic webpack config with ImageMinimizerPlugin using imagemin and jpegtran/optipng plugins.

const ImageMinimizerPlugin = require('image-minimizer-webpack-plugin');

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(jpe?g|png|gif|svg)$/i,
        type: 'asset',
      },
    ],
  },
  plugins: [
    new ImageMinimizerPlugin({
      minimizer: {
        implementation: ImageMinimizerPlugin.imageminMinify,
        options: {
          plugins: [
            ['jpegtran', { progressive: true }],
            ['optipng', { optimizationLevel: 5 }],
          ],
        },
      },
    }),
  ],
};