imagemin-webpack

Why

• No extra dependencies (imagemin-gifsicle, imagemin-pngquant) in dependencies section into package.json. You decide for yourself what plugins to use.

• This loader and plugin will optimize ANY images regardless of how they were added to webpack. image-webpack-loader don't optimize some images generating favicons-webpack-plugin or copy-webpack-plugin. ImageminWebpackPlugin don't optimize inlined images with url-loader.

• Images optimized when inlined with url-loader or svg-url-loader. This can't be done with imagemin-webpack-plugin.

• Throttle asynchronous images optimization (using maxConcurrency plugin option). This allows you to not overload a server when building.

• All tested.

• Persistent cache.

• (Optional) Don't crash building process if your have corrupted image(s).

Install

npm install imagemin-webpack --save-dev

Optionals

Images can be optimized in two modes:

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

Note:

• imagemin-mozjpeg can be configured in lossless and lossy mode.
• imagemin-svgo can be configured in lossless and lossy mode.

Explore the options to get the best result for you.

Recommended basic imagemin plugins for lossless optimization

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

Recommended basic imagemin plugins for lossy optimization

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

Basic

webpack.config.js

const ImageminPlugin = require("imagemin-webpack");

module.exports = {
  module: {
    rules: [
      {
        test: /\.(jpe?g|png|gif|svg)$/i,
        use: [
          {
            loader: "file-loader" // Or `url-loader` or your other loader
          }
        ]
      }
    ]
  },
  plugins: [
    // Make sure that the plugin is after any plugins that add images, example `CopyWebpackPlugin`
    new ImageminPlugin({
      bail: false, // Ignore errors on corrupted images
      cache: true,
      imageminOptions: {
        // Before using imagemin plugins make sure you have added them in `package.json` (`devDependencies`) and installed them

        // 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
                }
              ]
            }
          ]
        ]
      }
    })
  ]
};

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

Note: Make sure that plugin place after any plugins that add images or other assets which you want to optimized.

Standalone Loader

Documentation: Using loaders

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

webpack.config.js

const ImageminPlugin = require("imagemin-webpack");
const imageminGifsicle = require("imagemin-gifsicle");

module.exports = {
  module: {
    rules: [
      {
        test: /\.(jpe?g|png|gif|svg)$/i,
        use: [
          {
            loader: "file-loader" // Or `url-loader` or your other loader
          },
          {
            loader: ImageminPlugin.loader,
            options: {
              bail: false, // Ignore errors on corrupted images
              cache: true,
              imageminOptions: {
                plugins: ["gifsicle"]
              }
            }
          }
        ]
      }
    ]
  }
};

Standalone Plugin

Documentation: Using plugins

webpack.config.js

const ImageminWebpack = require("imagemin-webpack");
const imageminGifsicle = require("imagemin-gifsicle");

module.exports = {
  module: {
    rules: [
      {
        loader: "file-loader",
        options: {
          emitFile: true, // Don't forget emit images
          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({
      bail: false, // Ignore errors on corrupted images
      cache: true,
      imageminOptions: {
        plugins: ["gifsicle"]
      },
      // Disable `loader`
      loader: false
    })
  ]
};

Options

Plugin Options

| Name | Type | Default | Description | | :-------------------: | :---------------------------------------: | :----------------------------------------: | :------------------------------------------------------------------------------------------------------------------------ | | test | {String\/RegExp\|Array<String\|RegExp>} | /.(jpe?g|png|gif|svg)$/i | Test to match files against | | include | {String\/RegExp\|Array<String\|RegExp>} | undefined | Files to include | | exclude | {String\/RegExp\|Array<String\|RegExp>} | undefined | Files to exclude | | filter | {Function} | () => true | Allows filtering of images for optimization | | cache | {Boolean\|String} | false | Enable file caching | | bail | {Boolean} | compiler.options.bail | Emit warnings instead errors | | imageminOptions | {Object} | { plugins: [] } | Options for imagemin | | loader | {Boolean} | true | Automatically adding imagemin-loader (require for minification images using in url-loader, svg-url-loader or other) | | maxConcurrency | {Number} | Math.max(1, os.cpus().length - 1) | Maximum number of concurrency optimization processes in one time | | name | {String} | [hash].[ext] | The target asset name | | manifest | {Object} | undefined | Contain optimized list of images from other plugins |

test

Test to match files against.

webpack.config.js

const ImageminPlugin = require("imagemin-webpack");

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

include

Files to include.

webpack.config.js

const ImageminPlugin = require("imagemin-webpack");

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

exclude

Files to exclude.

webpack.config.js

const ImageminPlugin = require("imagemin-webpack");

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

filter

Allows filtering of images for optimization.

Return true to optimize the image, false otherwise.

webpack.config.js

const ImageminPlugin = require("imagemin-webpack");

module.exports = {
  plugins: [
    new ImageminPlugin({
      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

Enable/disable file caching. Default path to cache directory: node_modules/.cache/imagemin-webpack.

Be careful: you should remove cache manually when you enable cache using Function configuration for imagemin plugins and change option(s) for plugin(s) (for example for imagemin-gifsicle).

{Boolean}

Enable/disable file caching.

webpack.config.js

const ImageminPlugin = require("imagemin-webpack");

module.exports = {
  plugins: [
    new ImageminPlugin({
      cache: true
    })
  ]
};

{String}

Enable file caching and set path to cache directory.

webpack.config.js

const ImageminPlugin = require("imagemin-webpack");

module.exports = {
  plugins: [
    new ImageminPlugin({
      cache: "path/to/cache"
    })
  ]
};

bail

Emit warnings instead errors.

webpack.config.js

const ImageminPlugin = require("imagemin-webpack");

module.exports = {
  plugins: [
    new ImageminPlugin({
      bail: true
    })
  ]
};

imageminOptions

Options for imagemin.

More information and examples here.

webpack.config.js

const ImageminPlugin = require("imagemin-webpack");
const imageminGifsicle = require("imagemin-gifsicle");

module.exports = {
  plugins: [
    new ImageminPlugin({
      imageminOptions: {
        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 }
          ]
        ]
      }
    })
  ]
};

maxConcurrency

Maximum number of concurrency optimization processes in one time.

webpack.config.js

const ImageminPlugin = require("imagemin-webpack");

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

name

The target asset name.

webpack.config.js

const ImageminPlugin = require("imagemin-webpack");

module.exports = {
  plugins: [
    new ImageminPlugin({
      name: "[hash]-compressed.[ext]"
    })
  ]
};

manifest

Contain optimized list of images from other plugins.

Note: contains only assets compressed by plugin. Note: manifest will be contain list of optimized images only after emit event.

webpack.config.js

const ImageminPlugin = require("imagemin-webpack");
const ManifestPlugin = require("manifest-webpack-plugin");
const manifest = {};

module.exports = {
  plugins: [
    new ImageminPlugin({
      manifest
    }),
    new ManifestPlugin({
      // Contain compressed images
      manifest
    })
  ]
};

Loader Options

| Name | Type | Default | Description | | :-------------------: | :-----------------: | :---------------------: | :------------------------------------------ | | filter | {Function} | undefined | Allows filtering of images for optimization | | cache | {Boolean\|String} | false | Enable file caching | | bail | {Boolean} | compiler.options.bail | Emit warnings instead errors | | imageminOptions | {Object} | { plugins: [] } | Options for imagemin |

filter

Allows filtering of images for optimization.

Return true to optimize the image, false otherwise.

webpack.config.js

const ImageminPlugin = require("imagemin-webpack");
const imageminGifsicle = require("imagemin-gifsicle");

module.exports = {
  module: {
    rules: [
      {
        test: /\.(jpe?g|png|gif|svg)$/i,
        use: [
          {
            loader: "file-loader" // Or `url-loader` or your other loader
          },
          {
            loader: ImageminPlugin.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;
              },
              imageminOptions: {
                plugins: ["gifsicle"]
              }
            }
          }
        ]
      }
    ]
  }
};

cache

Enable file caching. Default path to cache directory: node_modules/.cache/imagemin-webpack.

{Boolean}

Enable/disable file caching.

webpack.config.js

const ImageminPlugin = require("imagemin-webpack");
const imageminGifsicle = require("imagemin-gifsicle");

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

{String}

Enable file caching and set path to cache directory.

webpack.config.js

const ImageminPlugin = require("imagemin-webpack");
const imageminGifsicle = require("imagemin-gifsicle");

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

bail

Emit warnings instead errors.

webpack.config.js

const ImageminPlugin = require("imagemin-webpack");
const imageminGifsicle = require("imagemin-gifsicle");

module.exports = {
  module: {
    rules: [
      {
        test: /\.(jpe?g|png|gif|svg)$/i,
        use: [
          {
            loader: "file-loader" // Or `url-loader` or your other loader
          },
          {
            loader: ImageminPlugin.loader,
            options: {
              bail: true,
              imageminOptions: {
                plugins: ["gifsicle"]
              }
            }
          }
        ]
      }
    ]
  }
};

imageminOptions

Options for imagemin.

More information and examples here.

webpack.config.js

const ImageminPlugin = require("imagemin-webpack");
const imageminGifsicle = require("imagemin-gifsicle");

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

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 ImageminPlugin = require("imagemin-webpack");
const imageminJpegtran = require("imagemin-jpegtran");

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

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

        return false;
      },
      imageminOptions: {
        plugins: [["jpegtran", { progressive: false }]]
      }
    })
  ]
};

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("imagemin-webpack");
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'}, …]
})();

Related

• imagemin - API for this package.
• image-webpack-loader - inspiration, thanks.
• imagemin-webpack-plugin - inspiration, thanks.

Contribution

Feel free to push your code if you agree with publishing under the MIT license.

Changelog

CHANGELOG

License

MIT