webp-loader

0.6.0 verified Sat Apr 25 auth: no javascript maintenance

Webpack loader that converts JPEG and PNG images to WebP format using imagemin-webp under the hood. Version 0.6.0 is the latest stable release. The loader integrates with webpack's loader pipeline and is typically combined with file-loader or multi-loader to produce both original and WebP versions. Key differentiator: it provides a direct bridge between webpack and imagemin-webp, allowing configuration via query string. However, it has seen only sporadic updates and is largely superseded by more modern image optimization plugins like imagemin-webpack-plugin.

Common errors

error Module not found: Error: Can't resolve 'webp-loader' ↓

cause webp-loader not installed as devDependency.

fix

Run npm install webp-loader --save-dev

error Error: webp-loader requires webpack and webpack-cli as peer dependencies. ↓

cause Missing peer dependencies.

fix

Install webpack and webpack-cli: npm install webpack webpack-cli --save-dev

error ValidationError: Invalid options object. webp-loader has been initialized using an options object that does not match the API schema. ↓

cause Options passed in query string format are not parsed correctly when not using the object form.

fix

Use the options object in webpack config: { loader: 'webp-loader', options: { quality: 80 } }

Warnings

deprecated Package has low maintenance and is essentially deprecated in favor of webpack plugins like imagemin-webpack-plugin or next-gen tools like sharp. ↓

fix Consider migrating to imagemin-webpack-plugin or sharp-based solutions.

gotcha Loader only works when chained after file-loader; if you want both original and WebP versions, you must use multi-loader or custom logic. ↓

fix Use multi-loader to apply two loader pipelines as shown in README.

gotcha Options must be passed as JSON string in query string or as object in 'options' property; the query string format may cause issues with complex options. ↓

fix Use object format via options property in webpack config.

breaking Peer dependency on webpack * (any version) may cause compatibility issues with webpack 5; not tested with webpack 5. ↓

fix Pin webpack version to 4 or manually adjust loader; consider migration.

Install

npm install webp-loader

yarn add webp-loader

pnpm add webp-loader

Imports

default

wrong

import webpLoader from 'webp-loader' // Not meant for direct import in application code

correct

// In webpack config: { test: /\.(jpe?g|png)$/i, use: ['file-loader', 'webp-loader'] }

webp-loader is a webpack loader and should be referenced in webpack configuration, not imported in source code.

multi

wrong

import multi from 'webp-loader' // multi is from multi-loader, not from webp-loader

correct

import multi from 'multi-loader' // Using multi-loader to bundle multiple loaders

When using multi-loader, import it separately; webp-loader does not export multi.

Quickstart

Shows basic webpack config to convert images to WebP using webp-loader alongside file-loader, including passing options.

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(jpe?g|png)$/i,
        use: [
          'file-loader',
          'webp-loader'
        ]
      }
    ]
  }
};

// With options (quality 80):
{
  test: /\.(jpe?g|png)$/i,
  use: [
    'file-loader',
    {
      loader: 'webp-loader',
      options: {
        quality: 80
      }
    }
  ]
}