image-webpack-loader

8.1.0 verified Sat Apr 25 auth: no javascript

Webpack loader that minifies PNG, JPEG, GIF, SVG and WEBP images using imagemin. Version 8.1.0 bundles optimizers for mozjpeg, optipng, pngquant, svgo, gifsicle, and optionally webp. Active development, new releases every few months. Key differentiator: seamless integration with webpack pipeline, automatic optimization on build. Compared to standalone imagemin, this plugin integrates directly into the webpack build process and allows per-rule configuration.

Common errors

error Module build failed: Error: dyld: Library not loaded: /usr/local/opt/libpng/lib/libpng16.16.dylib ↓

cause Missing libpng dependency on macOS.

fix

Run 'brew install libpng'.

error Error: Cannot find module 'imagemin' ↓

cause imagemin not installed or deduped incorrectly.

fix

Run 'npm install image-webpack-loader --save-dev' again, or manually install imagemin.

error ValidationError: Invalid configuration object. Webpack has been initialised using a configuration object that does not match the API schema. ↓

cause Using 'bypassOnDebug' with webpack 2+.

fix

Replace with options: { disable: true }.

error Error: The package "image-webpack-loader" is a loader that must be used with a matching file-loader or url-loader. ↓

cause Misconfigured webpack rule without file-loader before image-webpack-loader.

fix

Add 'file-loader' to the use array before 'image-webpack-loader'.

Warnings

gotcha Must be chained after file-loader or url-loader; otherwise images won't be emitted. ↓

fix Add 'file-loader' before 'image-webpack-loader' in the use array.

breaking Upgrading from webpack 1 to webpack 2+: 'bypassOnDebug' option is renamed to 'disable'. ↓

fix Use options: { disable: true } instead of bypassOnDebug.

deprecated imagemin-webp has engine constraints; it may fail on systems without libwebp. ↓

fix Ensure libwebp is installed or disable webp optimizer.

gotcha Node.js 12 is required for native modules compilation; may fail on newer or older versions. ↓

fix Use Node 12 LTS; for other versions, consider using image-minimizer-webpack-plugin.

breaking Imagemin plugins are native; they require compilation with node-gyp. Failure may occur on missing build tools. ↓

fix Install build tools: on macOS 'xcode-select --install', on Ubuntu 'apt-get install build-essential'.

gotcha SVGO may remove viewBox; if you rely on viewBox for responsive SVGs, disable SVGO. ↓

fix Set options: { svgo: { plugins: [{ removeViewBox: false }] } } or disabled: true.

Install

npm install image-webpack-loader

yarn add image-webpack-loader

pnpm add image-webpack-loader

Imports

image-webpack-loader
wrong
```
const imageWebpackLoader = require('image-webpack-loader')
```
correct
```
import imageWebpackLoader from 'image-webpack-loader'
```
ESM default import works; CommonJS require also works, but import is preferred for webpack

image-webpack-loader (as rule)

wrong

use: 'image-webpack-loader'

correct

use: ['file-loader', { loader: 'image-webpack-loader', options: { mozjpeg: {} } }]

Must be chained after file-loader or url-loader to output files

disable option
wrong
```
options: { bypassOnDebug: true }
```
correct
```
options: { disable: true }
```
bypassOnDebug is for webpack 1.x; use disable for webpack 2+

Quickstart

Configures webpack to minify images with image-webpack-loader, chained after file-loader, with custom options for each optimizer.

const path = require('path');

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
  },
  module: {
    rules: [
      {
        test: /\.(gif|png|jpe?g|svg)$/i,
        use: [
          'file-loader',
          {
            loader: 'image-webpack-loader',
            options: {
              mozjpeg: { progressive: true, quality: 65 },
              optipng: { enabled: false },
              pngquant: { quality: [0.65, 0.90], speed: 4 },
              gifsicle: { interlaced: false },
              webp: { quality: 75 },
            },
          },
        ],
      },
    ],
  },
};