0
# Image Webpack Loader
1

2
Image Webpack Loader is a webpack loader that optimizes and compresses images during the build process. It integrates with imagemin and various optimization plugins to automatically compress PNG, JPEG, GIF, SVG, and WEBP images as part of the webpack compilation pipeline.
3

4
## Package Information
5

6
- **Package Name**: image-webpack-loader
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install image-webpack-loader --save-dev`
10

11
## Core Imports
12

13
This package is used as a webpack loader, not directly imported in application code. It's configured in the webpack configuration file:
14

15
```javascript
16
// webpack.config.js
17
module.exports = {
18
  module: {
19
    rules: [{
20
      test: /\.(gif|png|jpe?g|svg)$/i,
21
      use: [
22
        'file-loader',
23
        {
24
          loader: 'image-webpack-loader',
25
          options: {
26
            // configuration options
27
          }
28
        }
29
      ]
30
    }]
31
  }
32
};
33
```
34

35
## Basic Usage
36

37
Basic configuration with default optimization settings:
38

39
```javascript
40
// webpack.config.js
41
module.exports = {
42
  module: {
43
    rules: [{
44
      test: /\.(gif|png|jpe?g|svg)$/i,
45
      use: [
46
        'file-loader',
47
        {
48
          loader: 'image-webpack-loader',
49
          options: {
50
            disable: process.env.NODE_ENV === 'development'
51
          }
52
        }
53
      ]
54
    }]
55
  }
56
};
57
```
58

59
Advanced configuration with custom optimizer settings:
60

61
```javascript
62
// webpack.config.js
63
module.exports = {
64
  module: {
65
    rules: [{
66
      test: /\.(gif|png|jpe?g|svg)$/i,
67
      use: [
68
        'file-loader',
69
        {
70
          loader: 'image-webpack-loader',
71
          options: {
72
            mozjpeg: {
73
              progressive: true,
74
              quality: 65
75
            },
76
            optipng: {
77
              enabled: false,
78
            },
79
            pngquant: {
80
              quality: [0.65, 0.90],
81
              speed: 4
82
            },
83
            gifsicle: {
84
              interlaced: false,
85
            },
86
            webp: {
87
              quality: 75
88
            }
89
          }
90
        }
91
      ]
92
    }]
93
  }
94
};
95
```
96

97
## Capabilities
98

99
### Webpack Loader Function
100

101
The main loader function that processes image content during webpack compilation.
102

103
```javascript { .api }
104
/**
105
 * Main webpack loader function that processes image content
106
 * @param {Buffer} content - Raw image buffer content
107
 * @returns {void} Calls webpack callback with optimized image data
108
 */
109
function imageWebpackLoader(content: Buffer): void;
110

111
// Loader properties
112
imageWebpackLoader.raw = true; // Indicates loader processes raw buffers
113
```
114

115
### Configuration Options
116

117
The loader accepts configuration options for controlling optimization behavior and individual optimizer settings.
118

119
```javascript { .api }
120
interface LoaderOptions {
121
  /** Skip processing when webpack debug mode is enabled (webpack v1) */
122
  bypassOnDebug?: boolean;
123
  /** Completely disable the loader processing */
124
  disable?: boolean;
125
  /** JPEG optimization options via mozjpeg */
126
  mozjpeg?: MozjpegOptions;
127
  /** PNG optimization options via optipng */
128
  optipng?: OptipngOptions;
129
  /** PNG optimization options via pngquant */
130
  pngquant?: PngquantOptions;
131
  /** GIF optimization options via gifsicle */
132
  gifsicle?: GifsicleOptions;
133
  /** SVG optimization options via svgo */
134
  svgo?: SvgoOptions;
135
  /** WebP conversion options via imagemin-webp */
136
  webp?: WebpOptions;
137
}
138
```
139

140
### Control Options
141

142
Options for controlling when the loader runs and whether it processes images.
143

144
```javascript { .api }
145
interface ControlOptions {
146
  /** 
147
   * Skip processing when webpack debug mode is enabled
148
   * Default: false
149
   * Note: Only works with webpack v1
150
   */
151
  bypassOnDebug?: boolean;
152
  
153
  /**
154
   * Completely disable the loader processing
155
   * Default: false 
156
   * Recommended for webpack v2+ instead of bypassOnDebug
157
   */
158
  disable?: boolean;
159
}
160
```
161

162
### JPEG Optimization (mozjpeg)
163

164
JPEG image optimization using the mozjpeg encoder.
165

166
```javascript { .api }
167
interface MozjpegOptions {
168
  /** Enable progressive JPEG encoding */
169
  progressive?: boolean;
170
  /** JPEG quality (0-100) */
171
  quality?: number;
172
  /** Disable mozjpeg optimization */
173
  enabled?: boolean;
174
  /** Additional mozjpeg-specific options */
175
  [key: string]: any;
176
}
177
```
178

179
### PNG Optimization (optipng)
180

181
PNG image optimization using the optipng optimizer.
182

183
```javascript { .api }
184
interface OptipngOptions {
185
  /** Optimization level (0-7) */
186
  optimizationLevel?: number;
187
  /** Disable optipng optimization */
188
  enabled?: boolean;
189
  /** Additional optipng-specific options */
190
  [key: string]: any;
191
}
192
```
193

194
### PNG Optimization (pngquant)
195

196
PNG image optimization using the pngquant optimizer with lossy compression.
197

198
```javascript { .api }
199
interface PngquantOptions {
200
  /** Quality range as [min, max] array (0-1) */
201
  quality?: [number, number];
202
  /** Compression speed (1-11, lower is slower but better) */
203
  speed?: number;
204
  /** Disable pngquant optimization */
205
  enabled?: boolean;
206
  /** Additional pngquant-specific options */
207
  [key: string]: any;
208
}
209
```
210

211
### GIF Optimization (gifsicle)
212

213
GIF image optimization using the gifsicle optimizer.
214

215
```javascript { .api }
216
interface GifsicleOptions {
217
  /** Enable interlaced GIFs */
218
  interlaced?: boolean;
219
  /** Optimization level (1-3) */
220
  optimizationLevel?: number;
221
  /** Disable gifsicle optimization */
222
  enabled?: boolean;
223
  /** Additional gifsicle-specific options */
224
  [key: string]: any;
225
}
226
```
227

228
### SVG Optimization (svgo)
229

230
SVG image optimization using the svgo optimizer.
231

232
```javascript { .api }
233
interface SvgoOptions {
234
  /** SVGO plugins configuration */
235
  plugins?: Array<string | object>;
236
  /** Disable svgo optimization */
237
  enabled?: boolean;
238
  /** Additional svgo-specific options */
239
  [key: string]: any;
240
}
241
```
242

243
### WebP Conversion
244

245
Convert images to WebP format using imagemin-webp. Unlike other optimizers, WebP is **disabled by default** and uses async loading.
246

247
```javascript { .api }
248
interface WebpOptions {
249
  /** WebP quality (0-100) */
250
  quality?: number;
251
  /** Enable WebP conversion (disabled by default) */
252
  enabled?: boolean;
253
  /** Additional webp-specific options */
254
  [key: string]: any;
255
}
256
```
257

258
**Note**: WebP optimization requires async loading of the imagemin-webp plugin and is disabled by default. Set `enabled: true` or provide configuration options to enable WebP processing.
259

260
## Usage Examples
261

262
### Development vs Production
263

264
Disable optimization during development for faster builds:
265

266
```javascript
267
// webpack.config.js
268
const isDevelopment = process.env.NODE_ENV === 'development';
269

270
module.exports = {
271
  module: {
272
    rules: [{
273
      test: /\.(gif|png|jpe?g|svg)$/i,
274
      use: [
275
        'file-loader',
276
        {
277
          loader: 'image-webpack-loader',
278
          options: {
279
            disable: isDevelopment
280
          }
281
        }
282
      ]
283
    }]
284
  }
285
};
286
```
287

288
### Selective Optimizer Configuration
289

290
Enable only specific optimizers:
291

292
```javascript
293
// webpack.config.js
294
module.exports = {
295
  module: {
296
    rules: [{
297
      test: /\.(gif|png|jpe?g|svg)$/i,
298
      use: [
299
        'file-loader',
300
        {
301
          loader: 'image-webpack-loader',
302
          options: {
303
            // Disable PNG optimizers, keep JPEG
304
            optipng: { enabled: false },
305
            pngquant: { enabled: false },
306
            mozjpeg: { 
307
              progressive: true,
308
              quality: 80
309
            },
310
            // Disable other optimizers
311
            gifsicle: { enabled: false },
312
            svgo: { enabled: false }
313
          }
314
        }
315
      ]
316
    }]
317
  }
318
};
319
```
320

321
### WebP Generation
322

323
Enable WebP conversion alongside original formats. **Note**: WebP is disabled by default and requires explicit enablement:
324

325
```javascript
326
// webpack.config.js
327
module.exports = {
328
  module: {
329
    rules: [{
330
      test: /\.(gif|png|jpe?g|svg)$/i,
331
      use: [
332
        'file-loader',
333
        {
334
          loader: 'image-webpack-loader',
335
          options: {
336
            // WebP is disabled by default - must be explicitly enabled
337
            webp: {
338
              enabled: true,  // Required to enable WebP processing
339
              quality: 75
340
            }
341
          }
342
        }
343
      ]
344
    }]
345
  }
346
};
347
```
348

349
### Deprecated Configuration Options
350

351
The following configuration options are deprecated but still supported with warnings:
352

353
```javascript { .api }
354
// Deprecated - use gifsicle.interlaced instead
355
interface DeprecatedGifsicleOptions {
356
  /** @deprecated Use gifsicle.interlaced instead */
357
  interlaced?: boolean;
358
}
359

360
// Deprecated - use mozjpeg.progressive instead  
361
interface DeprecatedMozjpegOptions {
362
  /** @deprecated Use mozjpeg.progressive instead */
363
  progressive?: boolean;
364
}
365

366
// Deprecated - use optipng.optimizationLevel instead
367
interface DeprecatedOptipngOptions {
368
  /** @deprecated Use optipng.optimizationLevel instead */
369
  optimizationLevel?: number;
370
}
371
```
372

373
## Error Handling
374

375
The loader will pass through errors from the underlying imagemin plugins and uses schema validation for configuration options. Common issues include:
376

377
- **Missing optional dependencies**: Install required imagemin plugins
378
- **Corrupted images**: The loader will call the webpack callback with the error
379
- **Plugin configuration errors**: Invalid options will be caught by schema validation using schema-utils
380
- **Deprecated option warnings**: Using deprecated options will emit webpack warnings
381

382
## Dependencies
383

384
### Required Dependencies
385
- `imagemin`: Core image processing library
386
- `loader-utils`: Webpack loader utilities
387
- `object-assign`: Object assignment polyfill
388
- `schema-utils`: Configuration validation
389

390
### Optional Image Optimizer Dependencies
391
- `imagemin-gifsicle`: GIF optimization
392
- `imagemin-mozjpeg`: JPEG optimization
393
- `imagemin-optipng`: PNG optimization
394
- `imagemin-pngquant`: PNG optimization with lossy compression
395
- `imagemin-svgo`: SVG optimization
396
- `imagemin-webp`: WebP conversion