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