optimize-image-loader

Optimize Image Loader

On-the-fly responsive image resizing, and A+ optimization. Uses mozjpeg, GIFsicle, OptiPNG, and SVGO, and even supports WebP. Use this image loader to handle all the following filetypes:

Filetype	Resizing	Optimization	Converting to
JPG	✅	✅	✅
PNG	✅	✅	✅
WebP	✅	✅	✅
SVG	N/A	✅	N/A
GIF		✅

Note: GIF resizing/conversion isn’t supported due to lack of support in sharp. Overall, it’s a small price to pay for the build speed of the sharp library.

Installation

npm i --save-dev optimize-image-loader

Usage

Simple usage

In your webpack config, add the following:

module: {
  rules: [
    {
      test: /(jpe?g|gif|png|svg)/i,
      use: 'optimize-image-loader'
    }
  ],
},

Then from your app, import image files normally. Specify specific optimizations per each file:

import imgSmall from './img/background-full.jpg?w=600&q=75'; /* 600px wide, 75% quality */
import imgLarge from './img/background-full.jpg?w=1200&q=50'; /* 1200px wide, 50% quality */

React

<img src={imgSmall} srcset={`${imgSmall} 600w, ${imgLarge} 1200w`} />

Vue

<img :src="imgSmall" :srcset="`${imgSmall} 600w, ${imgLarge} 1200w`">

Styled Components

const Header = styled.header`
  background-image: ${imgSmall};

  @media (min-width: 600px) {
    background-image: ${imgLarge};
  }
`;

Examples

Responsive (React)

import small from './myimage.jpg?w=600&q=80';
import medium from './myimage.jpg?w=1200&q=75';
import large from './myimage.jpg?w=1800&q=65';

..

<img
  srcset={`${medium} 1200w, ${large} 1800w, ${medium} 2x, ${large} 3x`}
  src={small}
  alt="image description"
/>

WebP (React)

import webP from './myimage.jpg?f=webp';
import fallback from './myimage.jpg';

...

<picture>
  <source srcset={webP} type="image/webp" />
  <source srcset={fallback} type="image/jpeg" />
  <img src={fallback} alt="image description" />
</picture>

Base64 inlined image (Styled Components)

import inlineBg from './myimage.jpg?inline';

...

const Wrapper = styled.div`
  background-image: url(${inlineBg});
`;

Inline SVG (React)

import inlineSVG from './myimage.svg?inline';

...

<div dangerouslySetInnerHtml={{ __html: inlineSVG }} />

Resizing pixel art

import pixelArt from './pixel-art?w=2048&interpolation=nearest';

Options

Specifying options per-image is the preferred method of this loader. By setting options per-file, you can fine-tune each image to find the best balance of quality and compression. Plus, you don’t have to touch your webpack config as your images change.

Query Options

Name	Default	Description
width	(original)	Set image width (in pixels). Leave height blank to auto-scale. Specify width and height to ensure image is smaller than both.
w		Shortcut for width.
height	(original)	Scale image height (in pixels). Leave width blank to auto-scale. Specify width and height to ensure image is smaller than both.
h		Shortcut for height.
quality	75 or 1	JPEG & WebP: specify 1–100, to set the image’s quality. GIF: specify 1 for least compressed, 3 for most compressed†. Compress as much as possible before degradation is noticable.
q		Shortcut for quality.
interpolation	'cubic'	When scaling, specify 'nearest' for nearest-neighbor (pixel art), 'cubic' for cubic interpolation, or 'lanczos2' or 'lanczos3' for Lanczos with a=2 or a=3. 'cubic' is this loader’s default (because it’s what most are used to), as opposed to'lanczos3' which is sharp’s default (present for other loaders)
inline	false	Set to ?inline or ?inline=true to return the individual image in base64 data URI, or raw SVG code 🎉.
format	(same)	Specify jpg, webp, or png to convert format from the original.
f		Shortcut for format.
skip	false	Set to ?skip or ?skip=true to bypass resizing & optimization entirely. This is particularly useful for SVGs that don’t optimize well.

^† GIFsicle uses a different 1–3 scale for compression, where 1 is least compressed and 3 is most, compared to other optimizers’ percentage quality scale. For GIFs, if you specify q=4 or greater, it will convert the percentage for you (4–33 is most compressed, 34–66 is medium compression, and 67–100 is light compression). Apologies if you really were trying to optimize your GIF to 1–3% quality.

Example

import myImage from './large.jpg?q=50&w=1200&f=webp';

Note: this loader will not upscale images because it increases file size without improving image quality. If you need to upscale pixel art, do it in CSS with image-rendering: crisp-edges.

Loader options

The main advantage of this loader is being able to specify quality and width inline, but there are some settings which make sense to set globally, such as SVGO settings, or a fallback quality. In these cases, pass options to the loader as usual:

Name	Default	Description
quality	75	Specify a number, 1–100, to set the fallback quality for all formats when none is specified.
q		Shortcut for quality.
outputPath	output.path	Override webpack’s default output path for these images.
emitFile	true	Set to false to skip processing file (setting from file-loader).
gif	(object)	Specify GIFsicle options.
jpg	(object)	Specify mozjpeg options.
jpeg		Alias of jpg.
png	(object)	Specify OptiPNG and PNGquant options together.
svgo	(object)	Override SVGO default settings.
svg		Alias of svgo (no other SVG options to set).

Note: because this loader passes images on to file-loader, url-loader, or raw-loader, the same is true of loader options! You should be able to use any options from those loaders within this config.

Example

module: {
  rules: [
    {
      test: /(jpe?g|gif|png|svg)$/i,
      use: {
        loader: 'optimize-image-loader',
        options: {
          quality: 75,
          jpg: {
            quality: 60,
          },
          svgo: {
            addClassesToSVGElement: true,
            mergePaths: true,
            removeStyleElement: true,
          },
          webp: {
            quality: 80,
          },
        },
      },
    },
  ],
},

WebP

Because WebP currently is only supported by Chrome, you’ll still need to configure fallbacks. For that reason, you can only convert per-file:

import webP from './original.jpg?f=webp';
import fallback from './original.jpg';

For tips on using WebP effectively, read this CSS Tricks article.

Troubleshooting

If python --version returns ^3 on your system, you’ll likely encounter the frequently-discussed node-gyp error:

Error: Python executable \"/usr/local/bin/python\" is v3.x.x, which is not supported by gyp.

If which python2.7 works on your system, run npm config set python python2.7 (or yarn config set python python2.7 if using yarn).

If your machine doesn’t have python2.7, install Python 2.x using Homebrew or some other means, and set that executable with npm config set python /path/to/python2 or yarn config set python /path/to/python2

Is this image loader for me?

If you:

• want to handle resizing AND optimization, not one or the other
• need to optimize & resize every image differently
• prefer writing srcset manually for complete control
• have a good understanding on image formats & optimization in general

Then this loader was made for you!

Special Thanks

This loader wouldn’t be possible without the significant achievements of:

• @kevva for imagemin
• @sokra, @d3viant0ne, and @michael-ciniawsky for file-loader, url-loader, and raw-loader
• @lovell for sharp