imagemin-webp-webpack-plugin

3.3.6 verified Sat Apr 25 auth: no javascript

Webpack plugin that converts JPEG, PNG, and GIF images to WebP format while preserving original files. Wraps imagemin, imagemin-webp, and imagemin-gif2webp. Compatible with Webpack 5, 4, and earlier. v3.3.6 stable release with regular dependency updates. Key differentiator: keeps originals and supports GIF via gif2webp. Configurable quality, extension override, detailed logs, silent mode, and strict error handling. A known issue exists with css-loader when importing .webp files that don't exist at build time.

Common errors

error Error: Cannot find module 'imagemin-webp' ↓

cause Missing peer dependency imagemin-webp or imagemin-gif2webp not installed.

fix

npm install imagemin-webp imagemin-gif2webp --save-dev

error TypeError: ImageminWebpWebpackPlugin is not a constructor ↓

cause Incorrect import: using named import instead of default or incorrect module system.

fix

Use const ImageminWebpWebpackPlugin = require('imagemin-webp-webpack-plugin'); or use default import with ES module interop.

error Configuration error: 'config' is not defined ↓

cause Options placed at top level instead of inside config array.

fix

Wrap options in config: [{ test: /regex/, options: {...} }]

error Webpack build fails: '...' file. This file was not converted to WebP. ↓

cause strict: true and an image failed conversion due to invalid format or corrupt file.

fix

Set strict: false to allow build to continue, or fix the problematic image file.

Warnings

gotcha Plugin order matters: should be placed last in plugins array to ensure original images are processed. ↓

fix Always put ImageminWebpWebpackPlugin as the last plugin in your webpack config plugins array.

gotcha css-loader@latest cannot resolve .webp imports before build time because .webp files do not exist yet. ↓

fix Use aliases or dynamic requires; refer to css-loader documentation for handling generated assets.

breaking v3.0.0 complete rewrite changed plugin API; config structure and defaults may differ from v2. ↓

fix Upgrade to v3 and adjust config to new format (config array, overrideExtension, strict, etc.).

deprecated Silent option overrides detailedLogs; setting silent: true disables all console output. ↓

fix Use silent: false to allow detailedLogs to work.

gotcha overrideExtension default is true, which replaces original extension; set to false to append .webp. ↓

fix Set overrideExtension: false if you want image.png.webp instead of image.webp.

Install

npm install imagemin-webp-webpack-plugin

yarn add imagemin-webp-webpack-plugin

pnpm add imagemin-webp-webpack-plugin

Imports

ImageminWebpWebpackPlugin

wrong

import ImageminWebpWebpackPlugin from 'imagemin-webp-webpack-plugin';

correct

const ImageminWebpWebpackPlugin = require('imagemin-webp-webpack-plugin');

This package does not provide ESM exports; use CommonJS require. No default export for ES modules.

ImageminWebpWebpackPlugin
wrong
```
import { ImageminWebpWebpackPlugin } from 'imagemin-webp-webpack-plugin';
```
correct
```
import ImageminWebpWebpackPlugin from 'imagemin-webp-webpack-plugin';
```
Named import will fail; the plugin only has a default export in CommonJS. ESM import may need a default interop.
Plugin configuration
wrong
```
new ImageminWebpWebpackPlugin({ quality: 75 })
```
correct
```
new ImageminWebpWebpackPlugin({ config: [{ test: /\.(jpe?g|png)/, options: { quality: 75 } }] })
```
Options must be nested inside config array items; top-level quality is ignored. Each config object requires test and options.

Quickstart

Shows full plugin configuration with separate rules for JPEG/PNG and GIF images, including all available options.

// webpack.config.js
const ImageminWebpWebpackPlugin = require('imagemin-webp-webpack-plugin');

module.exports = {
  plugins: [
    new ImageminWebpWebpackPlugin({
      config: [
        {
          test: /\.(jpe?g|png)/,
          options: {
            quality: 75
          }
        },
        {
          test: /\.gif/,
          options: {
            // imagemin-gif2webp options
          }
        }
      ],
      overrideExtension: true,
      detailedLogs: false,
      silent: false,
      strict: true
    })
  ]
};