Features:

• Optimize images using WebAssembly (runs in every environment)
• Image manipulation provided by various query params (resize, converting, low quality placeholders, ...)
• Build cache for images for faster builds
• Convert to WebP automatically during a webpack build
• Inline small images automatically
• ...

• Installation
• Options
• Usage
• License

npm install optimized-images-loader

Add the loader to your webpack configuration:

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif|svg|webp)$/i,
        use: [
          {
            loader: 'optimized-images-loader',
            options: {
              // see below for available options
            },
          },
        ],
      },
    ],
  },
};

You can now simply import images in your projects the same way as you would import source code.

import Header from './images/header.jpg';

export default () => (
  <div>
    <img src={Header} />
  </div>
);

This loader also provides a variety of query params to provide you even more options:

• ?include: Include the raw file directly (useful for SVG icons)
• ?webp: Convert an image to WebP on the fly
• ?inline: Force inlining an image (data-uri)
• ?url: Force an URL for a small image (instead of data-uri)
• ?original: Use the original image and do not optimize it
• ?lqip: Generate a low quality image placeholder
• ?colors: Extract the dominant colors of an image
• ?width: Resize an image to the given width
• ?height: Resize an image to the given height
• ?trace: Use traced outlines as loading placeholder (currently not supported)
• ?sprite: Use SVG sprites (currently not supported)

The image will now directly be included in your HTML without a data-uri or a reference to your file.

If this ?webp query parameter is specified, optimized-images-loader automatically converts the image to the new WebP format.

For browsers that don't yet support WebP, you may want to also provide a fallback using the <picture> tag or use the Img component which does this out of the box:

You can specify a limit for inlining images which will include it as a data-uri directly in your content instead of referencing a file if the file size is below that limit.

You usually don't want to specify a too high limit but there may be cases where you still want to inline larger images.

In this case, you don't have to set the global limit to a higher value but you can add an exception for a single image using the ?inline query options.

When you have an image smaller than your defined limit for inlining, it normally gets inlined automatically. If you don't want a specific small file to get inlined, you can use the ?url query param to always get back an image URL, regardless of the inline limit.

The image won't get optimized and used as it is. It makes sense to use this query param if you know an image already got optimized (e.g. during export) so it doesn't get optimized again a second time.

When using this resource query, a very small (about 10x10 pixel) image gets created. You can then display this image as a placeholder until the real (big) image has loaded.

This resource query returns you an array with hex values of the dominant colors of an image. You can also use this as a placeholder until the real image has loaded (e.g. as a background) like the Google Picture Search does.

The number of colors returned can vary and depends on how many different colors your image has.

import React from 'react';

export default () => (
  <div style={{ backgroundColor: require('./images/my-image.jpg?colors')[0] }}>...</div>
);

/**
 * require('./images/my-image.jpg?colors')
 *
 * returns for example
 *
 * ['#0e648d', '#5f94b5', '#a7bbcb', '#223240', '#a4c3dc', '#1b6c9c']
 */

Currently not supported

With the ?trace resource query, you can generate SVG image outlines which can be used as a placeholder while loading the original image.

Resizes the source image to the given width. If a height is additionally specified, it ensures the image covers both sizes and crops the remaining parts. If no height is specified, it will be automatically calculated to preserve the image aspect ratio.

import React from 'react';
import Image from './images/my-image.jpg?width=800';
import Thumbnail from './images/my-image.jpg?width=300&height=300';

export default () => (
  <div>
    <img src={Image} />
    <img src={Thumbnail} />
  </div>
);

Resizes the source image to the given height. If a width is additionally specified, it ensures the image covers both sizes and crops the remaining parts. If no width is specified, it will be automatically calculated to preserve the image aspect ratio.

import React from 'react';
import Image from './images/my-image.jpg?height=800';
import Thumbnail from './images/my-image.jpg?width=300&height=300';

export default () => (
  <div>
    <img src={Image} />
    <img src={Thumbnail} />
  </div>
);

Currently not supported

TODO: needs general documentation

Licensed under the MIT license.

© Copyright Cyril Wanner