ImageMinimizerWebpackPlugin

Plugin and Loader for <a href="http://webpack.js.org/">webpack</a> to optimize (compress) all images using <a href="https://github.com/imagemin/imagemin">imagemin</a>.
Do not worry about size of images, now they are always optimized/compressed.

npm node deps tests cover chat size

This plugin uses imagemin to optimize your images.

Getting Started

To begin, you'll need to install image-minimizer-webpack-plugin:

$ npm install image-minimizer-webpack-plugin --save-dev

Images can be optimized in two modes:

  1. Lossless (without loss of quality).
  2. Lossy (with loss of quality).

Note:

Explore the options to get the best result for you.

Recommended imagemin plugins for lossless optimization

npm install imagemin-gifsicle imagemin-jpegtran imagemin-optipng imagemin-svgo --save-dev

Recommended imagemin plugins for lossy optimization

npm install imagemin-gifsicle imagemin-mozjpeg imagemin-pngquant imagemin-svgo --save-dev

webpack.config.js

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

module.exports = {
  module: {
    rules: [
      {
        test: /\.(jpe?g|png|gif|svg)$/i,
        use: [
          {
            loader: 'file-loader', // Or `url-loader` or your other loader
          },
        ],
      },
    ],
  },
  plugins: [
    new ImageMinimizerPlugin({
      minimizerOptions: {
        // Lossless optimization with custom option
        // Feel free to experiment with options for better result for you
        plugins: [
          ['gifsicle', { interlaced: true }],
          ['jpegtran', { progressive: true }],
          ['optipng', { optimizationLevel: 5 }],
          [
            'svgo',
            {
              plugins: [
                {
                  removeViewBox: false,
                },
              ],
            },
          ],
        ],
      },
    }),
  ],
};

ℹ️ Only for 4 version of webpack: Make sure that plugin place after any plugins that add images or other assets which you want to optimized.**

ℹ️ If you want to use loader or plugin standalone see sections below, but this is not recommended.

Standalone Loader

Documentation: Using loaders

In your webpack.config.js, add the ImageMinimizerPlugin.loader, chained with the file-loader or url-loader:

webpack.config.js

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

module.exports = {
  module: {
    rules: [
      {
        test: /\.(jpe?g|png|gif|svg)$/i,
        use: [
          {
            loader: 'file-loader', // Or `url-loader` or your other loader
          },
          {
            loader: ImageMinimizerPlugin.loader,
            options: {
              severityError: 'warning', // Ignore errors on corrupted images
              minimizerOptions: {
                plugins: ['gifsicle'],
              },
            },
          },
        ],
      },
    ],
  },
};

Standalone Plugin

Documentation: Using plugins

webpack.config.js

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

module.exports = {
  module: {
    rules: [
      {
        loader: 'file-loader',
        options: {
          name: '[path][name].[ext]',
        },
        test: /\.(jpe?g|png|gif|svg)$/i,
      },
    ],
  },
  plugins: [
    // Make sure that the plugin placed after any plugins that added images
    new ImageminWebpack({
      severityError: 'warning', // Ignore errors on corrupted images
      minimizerOptions: {
        plugins: ['gifsicle'],
      },
      // Disable `loader`
      loader: false,
    }),
  ],
};

Options

Plugin Options

Name Type Default Description

Name

Type

Default

Description

test

{String\/RegExp\|Array<String\|RegExp>}

{String\/RegExp\|Array<String\|RegExp>} /.(jpe?g|png|gif|tif|webp|svg|avif)\$/i Test to match files against

Name

Type

Default

Description

include

{String\/RegExp\|Array<String\|RegExp>}

{String\/RegExp\|Array<String\|RegExp>} undefined Files to include

Name

Type

Default

Description

exclude

{String\/RegExp\|Array<String\|RegExp>}

{String\/RegExp\|Array<String\|RegExp>} undefined Files to exclude

Name

Type

Default

Description

filter

{Function}

{Function} () => true Allows filtering of images for optimization

Name

Type

Default

Description

cache

{Boolean\|String}

{Boolean\|String} true Enable file caching

Name

Type

Default

Description

severityError

{Boolean\|String}

{Boolean\|String} 'auto' Allows to choose how errors are displayed

Name

Type

Default

Description

minimizerOptions

{Object}

{Object} { plugins: [] } Options for imagemin

Name

Type

Default

Description

loader

{Boolean}

{Boolean} true Automatically adding imagemin-loader (require for minification images using in url-loader, svg-url-loader or other)

Name

Type

Default

Description

maxConcurrency

{Number}

{Number} Math.max(1, os.cpus().length - 1) Maximum number of concurrency optimization processes in one time

Name

Type

Default

Description

filename

{string}

{string} '[path][name][ext]' Allows to set the filename for the generated asset. Useful for converting to a webp

Name

Type

Default

Description

deleteOriginalAssets

{Boolean}

{Boolean} false Allows to delete the original asset. Useful for converting to a webp and remove original assets

test

Type: String|RegExp|Array<String|RegExp> Default: /\.(jpe?g\|png\|gif\|tif\|webp\|svg\|avif)\$/i

Test to match files against.

webpack.config.js

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

module.exports = {
  plugins: [
    new ImageMinimizerPlugin({
      test: /\.(jpe?g|png|gif|svg)$/i,
    }),
  ],
};

include

Type: String|RegExp|Array<String|RegExp> Default: undefined

Files to include.

webpack.config.js

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

module.exports = {
  plugins: [
    new ImageMinimizerPlugin({
      include: /\/includes/,
    }),
  ],
};

exclude

Type: String|RegExp|Array<String|RegExp> Default: undefined

Files to exclude.

webpack.config.js

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

module.exports = {
  plugins: [
    new ImageMinimizerPlugin({
      exclude: /\/excludes/,
    }),
  ],
};

filter

Type: Function Default: () => true

Allows filtering of images for optimization.

Return true to optimize the image, false otherwise.

webpack.config.js

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

module.exports = {
  plugins: [
    new ImageMinimizerPlugin({
      filter: (source, sourcePath) => {
        // The `source` argument is a `Buffer` of source file
        // The `sourcePath` argument is an absolute path to source
        if (source.byteLength < 8192) {
          return false;
        }

        return true;
      },
    }),
  ],
};

cache

⚠ Ignored in webpack 5! Please use https://webpack.js.org/configuration/other-options/#cache.

Type: Boolean|String Default: true

Enable/disable file caching. Default path to cache directory: node_modules/.cache/image-minimizer-webpack-plugin.

{Boolean}

Enable/disable file caching.

webpack.config.js

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

module.exports = {
  plugins: [
    new ImageMinimizerPlugin({
      cache: false,
    }),
  ],
};
{String}

Enable file caching and set path to cache directory.

webpack.config.js

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

module.exports = {
  plugins: [
    new ImageMinimizerPlugin({
      cache: 'path/to/cache',
    }),
  ],
};

severityError

Type: Boolean|String Default: 'auto'

Allows to choose how errors are displayed.

Сan have the following values:

  • 'auto' - emit warnings in development mode and emit errors in production mode (default behavior)
  • false or 'off' - suppresses errors and warnings
  • 'warning' - emit warnings instead errors
  • true or 'error' - emit errors

webpack.config.js

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

module.exports = {
  plugins: [
    new ImageMinimizerPlugin({
      severityError: 'warning',
    }),
  ],
};

minimizerOptions

Type: Object Default: { plugins: [] }

Options for imagemin.

More information and examples here.

webpack.config.js

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

module.exports = {
  plugins: [
    new ImageMinimizerPlugin({
      minimizerOptions: {
        plugins: [
          // Name
          'gifsicle',
          // Name with options
          ['mozjpeg', { quality: 80 }],
          // Full package name
          [
            'imagemin-svgo',
            {
              plugins: [
                {
                  removeViewBox: false,
                },
              ],
            },
          ],
          [
            // Custom package name
            'nonstandard-imagemin-package-name',
            { myOptions: true },
          ],
        ],
      },
    }),
  ],
};

loader

Type: Boolean Default: true

Automatically adding imagemin-loader.

webpack.config.js

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

module.exports = {
  plugins: [
    new ImageMinimizerPlugin({
      loader: false,
    }),
  ],
};

maxConcurrency

Type: Number Default: Math.max(1, os.cpus().length - 1)

Maximum number of concurrency optimization processes in one time.

webpack.config.js

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

module.exports = {
  plugins: [
    new ImageMinimizerPlugin({
      maxConcurrency: 3,
    }),
  ],
};

filename

Type: String Default: '[path][name][ext]'

Allows to set the filename for the generated asset. Useful for converting to a webp.

webpack.config.js

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

module.exports = {
  plugins: [
    // Images are converted to `webp` and the original assets have been kept
    new ImageMinimizerPlugin({
      test: /\.(png)$/i,
      filename: '[path][name].webp',
      minimizerOptions: {
        plugins: ['imagemin-webp'],
      },
    }),
  ],
};

deleteOriginalAssets

Type: Boolean Default: false

Allows to remove original assets. Useful for converting to a webp and remove original assets

i Doesn't make sense if you haven't changed the original value of the filename option

webpack.config.js

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

module.exports = {
  plugins: [
    // Images are converted to `webp` and the original assets have been removed
    new ImageMinimizerPlugin({
      test: /\.(png)$/i,
      deleteOriginalAssets: true,
      filename: '[path][name].webp',
      minimizerOptions: {
        plugins: ['imagemin-webp'],
      },
    }),
  ],
};

To generate and compress the original assets:

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

module.exports = {
  plugins: [
    // And the original assets will be compressed
    new ImageMinimizerPlugin({
      test: /\.(png)$/i,
      minimizerOptions: {
        plugins: ['pngquant'],
      },
    }),
    // Images are converted to `webp` and the original assets have been removed
    new ImageMinimizerPlugin({
      test: /\.(png)$/i,
      deleteOriginalAssets: false,
      filename: '[path][name].webp',
      minimizerOptions: {
        plugins: ['imagemin-webp'],
      },
    }),
  ],
};

Loader Options

Name Type Default Description

Name

Type

Default

Description

filter

{Function}

{Function} undefined Allows filtering of images for optimization

Name

Type

Default

Description

cache

{Boolean\|String}

{Boolean\|String} true Enable file caching

Name

Type

Default

Description

severityError

{Boolean\|String}

{Boolean\|String} 'auto' Allows to choose how errors are displayed

Name

Type

Default

Description

minimizerOptions

{Object}

{Object} { plugins: [] } Options for imagemin

Name

Type

Default

Description

filename

{string}

{string} '[path][name][ext]' Allows to set the filename for the generated asset. Useful for converting to a webp

Name

Type

Default

Description

deleteOriginalAssets

{Boolean}

{Boolean} false Allows to delete the original asset. Useful for converting to a webp and remove original assets

filter

Type: Function Default: () => true

Allows filtering of images for optimization.

Return true to optimize the image, false otherwise.

webpack.config.js

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

module.exports = {
  module: {
    rules: [
      {
        test: /\.(jpe?g|png|gif|svg)$/i,
        use: [
          {
            loader: 'file-loader', // Or `url-loader` or your other loader
          },
          {
            loader: ImageMinimizerPlugin.loader,
            options: {
              cache: true,
              filter: (source, sourcePath) => {
                // The `source` argument is a `Buffer` of source file
                // The `sourcePath` argument is an absolute path to source
                if (source.byteLength < 8192) {
                  return false;
                }

                return true;
              },
              minimizerOptions: {
                plugins: ['gifsicle'],
              },
            },
          },
        ],
      },
    ],
  },
};

cache

Type: Boolean\|String Default: true

Enable file caching. Default path to cache directory: node_modules/.cache/image-minimizer-webpack-plugin.

{Boolean}

Enable/disable file caching.

webpack.config.js

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

module.exports = {
  module: {
    rules: [
      {
        test: /\.(jpe?g|png|gif|svg)$/i,
        use: [
          {
            loader: 'file-loader', // Or `url-loader` or your other loader
          },
          {
            loader: ImageMinimizerPlugin.loader,
            options: {
              cache: false,
              minimizerOptions: {
                plugins: ['gifsicle'],
              },
            },
          },
        ],
      },
    ],
  },
};
{String}

Enable file caching and set path to cache directory.

webpack.config.js

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

module.exports = {
  module: {
    rules: [
      {
        test: /\.(jpe?g|png|gif|svg)$/i,
        use: [
          {
            loader: 'file-loader', // Or `url-loader` or your other loader
          },
          {
            loader: ImageMinimizerPlugin.loader,
            options: {
              cache: 'path/to/cache',
              minimizerOptions: {
                plugins: ['gifsicle'],
              },
            },
          },
        ],
      },
    ],
  },
};

severityError

Type: Boolean|String Default: 'auto'

Allows to choose how errors are displayed.

Сan have the following values:

  • 'auto' - emit warnings in development mode and emit errors in production mode (default behavior)
  • false or 'off' - suppresses errors and warnings
  • 'warning' - emit warnings instead errors
  • true or 'error' - emit errors

webpack.config.js

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

module.exports = {
  module: {
    rules: [
      {
        test: /\.(jpe?g|png|gif|svg)$/i,
        use: [
          {
            loader: 'file-loader', // Or `url-loader` or your other loader
          },
          {
            loader: ImageMinimizerPlugin.loader,
            options: {
              severityError: 'warning',
              minimizerOptions: {
                plugins: ['gifsicle'],
              },
            },
          },
        ],
      },
    ],
  },
};

minimizerOptions

Type: Object Default: { plugins: [] }

Options for imagemin.

Options for imagemin

webpack.config.js

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

module.exports = {
  module: {
    rules: [
      {
        test: /\.(jpe?g|png|gif|svg)$/i,
        use: [
          {
            loader: 'file-loader', // Or `url-loader` or your other loader
          },
          {
            loader: ImageMinimizerPlugin.loader,
            options: {
              severityError: 'warning',
              minimizerOptions: {
                plugins: [
                  ['gifsicle', { interlaced: true, optimizationLevel: 3 }],
                ],
              },
            },
          },
        ],
      },
    ],
  },
};

filename

Type: String Default: '[path][name][ext]'

Allows to set the filename for the generated asset. Useful for converting to a webp.

webpack.config.js

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

module.exports = {
  module: {
    rules: [
      {
        test: /\.(jpe?g|png|gif)$/i,
        use: [
          {
            loader: 'file-loader', // Or `url-loader` or your other loader
          },
          {
            loader: ImageMinimizerPlugin.loader,
            options: {
              filename: '[path][name].webp',
              minimizerOptions: {
                plugins: ['imagemin-webp'],
              },
            },
          },
        ],
      },
    ],
  },
};

deleteOriginalAssets

Type: Boolean Default: false

Allows to keep the original asset. Useful for converting to a webp and remove original assets.

i Doesn't make sense if you haven't changed the original value of the filename option

webpack.config.js

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

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png)$/i,
        use: [
          {
            loader: 'file-loader', // Or `url-loader` or your other loader
          },
          {
            loader: ImageMinimizerPlugin.loader,
            options: {
              // PNG images are converted to WEBP, and the originals will keep
              deleteOriginalAssets: false,
              filename: '[path][name].webp',
              minimizerOptions: {
                plugins: ['imagemin-webp'],
              },
            },
          },
        ],
      },
    ],
  },
};

Additional API

normalizeConfig(config)

The function normalizes configuration (converts plugins names and options to Functions) for using in imagemin package directly.

const imagemin = require('imagemin');
const { normalizeConfig } = require('image-minimizer-webpack-plugin');
const imageminConfig = normalizeConfig({
  plugins: [
    'jpegtran',
    [
      'pngquant',
      {
        quality: [0.6, 0.8],
      },
    ],
  ],
});

/*
  console.log(imageminConfig);
  =>
  {
    plugins: [Function, Function],
    pluginsMeta: [
      { name: "imagemin-jpegtran", version: "x.x.x", options: {} },
      { name: "imagemin-pngquant", version: "x.x.x", options: { quality: [0.6, 0.8] }
    ]
  }
*/

(async () => {
  const files = await imagemin(['images/*.{jpg,png}'], {
    destination: 'build/images',
    plugins: imageminConfig.plugins,
  });

  console.log(files);
  // => [{data: <Buffer 89 50 4e …>, path: 'build/images/foo.jpg'}, …]
})();

Examples

Optimize images based on size

You can use difference options (like progressive/interlaced and etc) based on image size (example - don't do progressive transformation for small images).

What is progressive image? Answer here.

webpack.config.js

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

module.exports = {
  minimizer: [
    new ImageMinimizerPlugin({
      // Only apply this one to files equal to or over 8192 bytes
      filter: (source) => {
        if (source.byteLength >= 8192) {
          return true;
        }

        return false;
      },
      minimizerOptions: {
        plugins: [['jpegtran', { progressive: true }]],
      },
    }),
    new ImageMinimizerPlugin({
      // Only apply this one to files under 8192
      filter: (source) => {
        if (source.byteLength < 8192) {
          return true;
        }

        return false;
      },
      minimizerOptions: {
        plugins: [['jpegtran', { progressive: false }]],
      },
    }),
  ],
};

Optimize and transform images to webp

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

module.exports = {
  plugins: [
    new ImageMinimizerPlugin({
      minimizerOptions: {
        plugins: ['pngquant'],
      },
    }),
    new ImageMinimizerPlugin({
      deleteOriginalAssets: false,
      filename: '[path][name].webp',
      minimizerOptions: {
        plugins: ['imagemin-webp'],
      },
    }),
  ],
};

Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

CONTRIBUTING

License

MIT