image-optimize-loader

This special image optimize webpack loader can:

• Help you [encode image / inline image] and [compress image / minify image] when loaded with webpack.

• Help you tranform PNG/JPG images into WEBP when needed.

Its special encoding(inlining) ability is stronger than url-loader, especially useful for performance-optimization scenarios. And it will compress images automatically both for emited image file or inlined images string, without complicated configurations.

Getting Started

To begin, you'll need to install img-optimize-loader:

1$ npm install img-optimize-loader --save-dev

Then, all you need to do is adding the img-optimize-loader to your webpack config.

You don't need to specify extra loaders like file-loader or url-loader for your images. img-optimize-loader will automaticlly handle everything.

For example:

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        test: /\.(png|jpe?g|webp|git|svg|)$/i,
6        use: [
7          {
8            loader: 'img-optimize-loader',
9          },
10        ],
11      },
12    ],
13  },
14};

You can import your image. Compression and encoding will happen according to your configuration.

1import file from 'image.png';

Features

1. Encode images and inline them into js/css files.

Encode image with base64, utf8, latin1, hex, ascii, binary,ucs2

Inline image into JS / CSS files

When I use url-loader to encode images, I can only depend on limit configuration to decide whether to enable encodeing. As we know, the image whose size was smaller than the limit, will always be encoded.

But I found problems when i want to inline a large size image into my entry jsbundle because this image is so important to my first screen rendering; Or when I don't want to inline trivial small images because there is no need to load them in time. I can't improve my page performance in this scene with url-loader.

Now with img-optimize-loader we can take more flexible control on this. We can specify every image whether or not to be encoded easily（using file query）regardless of limit configuration. Still, if we don't specify it, limit configuration will take control.

index.js

1// Always let foo.png be encoded and inlined here regardless of 'limit configuration'
2import encodedImage from './encode.png?__inline';
3
4// Always emit real image file regardless of 'limit configuration'
5import fileImage from './emit.png?__antiInline';

The query symbol __inline and __antiInline can be customed by your self.

2. Compress your images

The compression algorithm is based on imagemin. It supports images in png, jpg, gif, webp, svg format.

• minify JPEG image
• minify PNG image
• minify GIF image
• minify WEBP image
• minify SVG image

We support 3 levels for you to compress images automaticlly.

level	description
loseless	Only use lossless compress algorithm. Only support png/webp/svg images
low	Cause a little distortion，and get small files. It will compress png/jpg/svg/gif images
high	Cause more distortion，and get smaller files. It will compress png/jpg/svg/gif images

To deal with webp images, please refer webp

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        test: /\.(png|jpe?g|webp|git|svg|)$/i,
6        use: [
7          {
8            loader: `img-optimize-loader`,
9            options: {
10              compress: {
11                // This will take more time and get smaller images.
12                mode: 'high', // 'lossless', 'low'
13                disableOnDevelopment: true,
14              },
15            },
16          },
17        ],
18      },
19    ],
20  },
21};

And you can also adjust the compression manually using more params.

1module.exports = {
2  module: {
3    rules: [
4      {
5        test: /\.(png|jpe?g|webp|git|svg|)$/i,
6        use: [
7          {
8            loader: 'img-optimize-loader',
9            options: {
10              compress: {
11                // loseless compression for png
12                optipng: {
13                  optimizationLevel: 4,
14                },
15                // lossy compression for png. This will generate smaller file than optipng.
16                pngquant: {
17                  quality: [0.2, 0.8],
18                },
19                // Compression for webp.
20                // You can also tranform jpg/png into webp.
21                webp: {
22                  quality: 100,
23                },
24                // Compression for svg.
25                svgo: true,
26                // Compression for gif.
27                gifsicle: {
28                  optimizationLevel: 3,
29                },
30                // Compression for jpg.
31                mozjpeg: {
32                  progressive: true,
33                  quality: 60,
34                },
35              },
36            },
37          },
38        ],
39      },
40    ],
41  },
42};

3. Transform your png/jpg into webp

When you enable compress.webp, it will transform your png/jpg into webp files, and there will be no png/jpg files generated. Your source code will directly use webp file instead of png/jpg.

Generally, when you can use webp without incompatibility problem , there will be no need to use png or jpg any more, because webp files are always smaller than their png/jpg origin.

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        test: /\.(png|jpe?g|webp|git|svg|)$/i,
6        use: [
7          {
8            loader: `img-optimize-loader`,
9            options: {
10              compress: {
11                // This will transform your png/jpg into webp.
12                webp: true,
13                disableOnDevelopment: true,
14              },
15            },
16          },
17        ],
18      },
19    ],
20  },
21};

Referer to webp configuration for details.

index.js

1// This two images will be transformed into webp and your source code will use the webp format.
2import encodedImage from './encode.png';
3
4import fileImage from './test.jpg';

Options

name

Type: [string] Default: 'imgs/[contenthash].[ext]'

Specifies a custom filename template for the target images(s) using the query parameter name. For example, to emit a image from your context directory into the output directory retaining the full directory structure, you might use:

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          name: '[path][name].[ext]',
8        },
9      },
10    ],
11  },
12};

esModule

Type: [Boolean] Default: false

Decides js modules generated from image. Whether to use the ES modules or commonjs.

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          esModule: false,
8        },
9      },
10    ],
11  },
12};

outputPath

Type: String|Function Default: undefined

Specify a filesystem path where the target file(s) will be placed.

String

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        test: /\.(png|jpe?g|gif)$/i,
6        loader: 'img-optimize-loader',
7        options: {
8          outputPath: 'images',
9        },
10      },
11    ],
12  },
13};

Function

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        test: /\.(png|jpe?g|gif)$/i,
6        loader: 'img-optimize-loader',
7        options: {
8          outputPath: (url, resourcePath, context) => {
9            return `output_path/${url}`;
10          },
11        },
12      },
13    ],
14  },
15};

publicPath

Type: String|Function Default: __webpack_public_path__+outputPath

Specifies a custom public path for the target file(s).

String

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        test: /\.(png|jpe?g|gif)$/i,
6        loader: 'img-optimize-loader',
7        options: {
8          publicPath: 'assets',
9        },
10      },
11    ],
12  },
13};

Function

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        test: /\.(png|jpe?g|gif)$/i,
6        loader: 'img-optimize-loader',
7        options: {
8          publicPath: (url, resourcePath, context) => {
9            return `public_path/${url}`;
10          },
11        },
12      },
13    ],
14  },
15};

context

Type: String Default: context

Specifies a custom file context.

emitFile

Type: Boolean Default: true

If true, emits a file (writes a file to the filesystem). If false, the loader will return a public URI but will not emit the file. It is often useful to disable this option for server-side packages.

inline.symbol

Type: [String] Default: __inline

Query symbol used to specify the image that should be encoded and inlined.

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          inline: {
8            symbol: '__inline',
9          },
10        },
11      },
12    ],
13  },
14};

inline.antiSymbol

Type: [String] Default: __antiInline

Query symbol used to specify the image that should not be encoded and inlined.

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          inline: {
8            antiSymbol: '__antiInline',
9          },
10        },
11      },
12    ],
13  },
14};

inline.limit

Type: [Boolean|Number|String] Default: 5000

A Number or String specifying the maximum size of a encoded image in bytes. If the image size is equal or greater than the limit file-loader will be used (by default) and all query parameters are passed to it.

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          inline: {
8            antiSymbol: '__antiInline',
9          },
10        },
11      },
12    ],
13  },
14};

inline.mimetype

Type: Boolean|String Default: based from mime-types

Specify the mimetype which the file will be inlined with. If unspecified the mimetype value will be used from mime-types.

Boolean

The true value allows to generation the mimetype part from mime-types. The false value removes the mediatype part from a Data URL (if omitted, defaults to text/plain;charset=US-ASCII).

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          inline: {
8            mimetype: false,
9          },
10        },
11      },
12    ],
13  },
14};

String

Sets the MIME type for the file to be transformed.

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          inline: {
8            mimetype: 'image/png',
9          },
10        },
11      },
12    ],
13  },
14};

inline.encoding

Type: Boolean|String Default: base64

Specify the encoding which the file will be inlined with. If unspecified the encoding will be base64.

Boolean

If you don't want to use any encoding you can set encoding to false however if you set it to true it will use the default encoding base64.

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        test: /\.svg$/i,
6        use: [
7          {
8            loader: `img-optimize-loader`,
9            options: {
10              inline: {
11                encoding: false,
12              },
13            },
14          },
15        ],
16      },
17    ],
18  },
19};

String

It supports Node.js Buffers and Character Encodings which are ["utf8","utf16le","latin1","base64","hex","ascii","binary","ucs2"].

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          inline: {
8            encoding: 'utf8',
9          },
10        },
11      },
12    ],
13  },
14};

inline.generator

Type: Function Default: (mimetype, encoding, content, resourcePath) => mimetype;encoding,base64_content

You can create you own custom implementation for encoding data.

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          inline: {
8            // The `mimetype` and `encoding` arguments will be obtained from your options
9            // The `resourcePath` argument is path to file.
10            generator: (content, mimetype, encoding, resourcePath) => {
11              if (/\.html$/i.test(resourcePath)) {
12                return `data:${mimetype},${content.toString()}`;
13              }
14
15              return `data:${mimetype}${
16                encoding ? `;${encoding}` : ''
17              },${content.toString(encoding)}`;
18            },
19          },
20        },
21      },
22    ],
23  },
24};

compress.mode

Type: string Default: low

Specify the compress level.

level	description
loseless	Only use lossless compress algorithm. Only support png/webp/svg images
low	Cause a little distortion，and get small files. It will compress png/jpg/svg/webp/gif images
high	Cause more distortion，and get smaller files. It will compress png/jpg/svg/webp/gif images

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          compress: {
8            mode: 'high',
9          },
10        },
11      },
12    ],
13  },
14};

compress.mozjpeg

Type: [Object|Boolean]

Compress jpg images.

Boolean

If you don't want to compress jpg files, you can set mozjpeg to false however if you set it to true it will generator the settings according to compress.mode configuration.

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          compress: {
8            mozjpeg: false,
9          },
10        },
11      },
12    ],
13  },
14};

Object

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          compress: {
8            mozjpeg: {},
9          },
10        },
11      },
12    ],
13  },
14};

Link to mozjpeg configuration

compress.optipng

Type: [Object|Boolean]

Compress png images.

Boolean

If you don't want to use optipng to compress png files, you can set optipng to false however if you set it to true it will generator the settings according to compress.mode configuration.

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          compress: {
8            optipng: false,
9          },
10        },
11      },
12    ],
13  },
14};

Object

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          compress: {
8            optipng: {},
9          },
10        },
11      },
12    ],
13  },
14};

Link to optipng configuration

compress.pngquant

Type: [Object|Boolean]

Compress png images.

Boolean

If you don't want to use pngquant to compress png files, you can set pngquant to false however if you set it to true it will generator the settings according to compress.mode configuration.

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          compress: {
8            pngquant: false,
9          },
10        },
11      },
12    ],
13  },
14};

Object

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          compress: {
8            pngquant: {},
9          },
10        },
11      },
12    ],
13  },
14};

Link to pngquant configuration

compress.svgo

Type: [Object|Boolean]

Compress svg images.

Boolean

If you don't want to compress svg files, you can set svgo to false however if you set it to true it will generator the settings according to compress.mode configuration.

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          compress: {
8            svgo: false,
9          },
10        },
11      },
12    ],
13  },
14};

Object

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          compress: {
8            svgo: {},
9          },
10        },
11      },
12    ],
13  },
14};

Link to svgo configuration

compress.gifsicle

Type: [Object|Boolean]

Compress gif images.

Boolean

If you don't want to compress gif files, you can set gifsicle to false however if you set it to true it will generator the settings according to compress.mode configuration.

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          compress: {
8            gifsicle: false,
9          },
10        },
11      },
12    ],
13  },
14};

Object

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          compress: {
8            gifsicle: {},
9          },
10        },
11      },
12    ],
13  },
14};

compress.webp

Type: [Object|Boolean] Default: false

Transform png/jpg into webp. Compress webp files.

Boolean

If you want to transform png/jpg into webp, you can set webp to true.

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          compress: {
8            webp: true,
9          },
10        },
11      },
12    ],
13  },
14};

Object

webpack.config.js

1module.exports = {
2  module: {
3    rules: [
4      {
5        loader: `img-optimize-loader`,
6        options: {
7          compress: {
8            webp: {},
9          },
10        },
11      },
12    ],
13  },
14};

Link to webp configuration

Inspiration

• image-webpack-loader
• url-loader
• imagemin

License

MIT