Usage

Importing the image

The Webpack loader is designed for importing images into a Javascript file. This is a pattern that works well with libraries such as React, Vue, Angular, etc, as it allows you to then process that image import, for exemple to generate a <picture> element.

ES Module

import image from "path/to/image.jpg";

CommonJS

const image = require("path/to/image.jpg");

When you import an image, the loader will transform that image behind the scenes by processing it with IPP using the configured pipeline, saving each generated format along with other bundled website assets.

The import is replaced with a JavaScript object that contains information about the export, such as the URL of each format.

API Reference

Table

key	type	description
pipeline	object	The pipeline used to process images with (required)
manifest	object	Enables manifest mode, additionaly specifying the manifest mappings
devBuild	boolean	Force image processing during development/testing
esModule	boolean	Create ES modules instead of CommonJS modules
outputPath	string	Specify directory where results should be saved (relative to build directory)

_{The Options object}

TypeScript

Loader options

interface Options {
  devBuild?: boolean;
  manifest?: ManifestMappings;
  esModule?: boolean;
  outputPath?: string;
  pipeline: Pipeline;
}

Import mode

There are two import modes available. Both modes generate the same image formats.

Simple mode

Simple mode will attempt to do some sane processing of the pipeline result to make it as easy as possible to plug it into a <picture> element.

It will group images together by format, generating a srcset string for each one along with each image's dimensions, and attempt to select the best "fallback" image for the src property. Additionally, the original height and width are provided to make it easier to calculate layout if you plan on loading images lazily.

Example simple export

import image from "path/to/image.jpg";

// image is an object
{
  src: "f8c1421b4334c1c9.jpg",
  width: 1920,
  height: 1080,
  srcset: {
    "image/jpeg": "46de0d3babc16786.jpg 720w, 885001be48ef4667.jpg 1920w",
    "image/webp": "f876c5d47c6c0866.webp 720w, 5eb716978a1b5a09.webp 1920w"
  }
}

Manifest mode

Manifest mode gives you more control over the information that you would like to extract from the pipeline result. It is enabled by specifying manifest key in the loader's options.

It is practically identical to the implementation used by the CLI, with support for selectors, limiting, except that you only receive the manifest item for that particular import, and not a list of every single sucessful result. Take a look at the manifest documentation for the CLI to learn more.

Example manifest export

import image from "path/to/image.jpg";

// image is an object
{
  s: {
    w: 1920,
    h: 1080,
  },
  f: [
    {
      w: 720,
      f: "jpeg",
      p: "46de0d3babc16786.jpg"
    },
    {
      w: 720,
      f: "webp",
      p: "f876c5d47c6c0866.webp"
    },
    ...
  ]
}

Development builds

To make the development experience more pleasant, images will not be processed in non-production environments. This is determined by the NODE_ENV environmental variable which should be set automatically by Webpack. Instead, images will be passed through untouched with a saveKey of true.

It is possible to override this behaviour by specifying a devBuild: true key in the loader's options. This may be useful to preview how images will look in the final build.