Skip to main content

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.

import image from "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#

keytypedescription
pipelineobjectThe pipeline used to process images with (required)
manifestobjectEnables manifest mode, additionaly specifying the manifest mappings
devBuildbooleanForce image processing during development/testing
esModulebooleanCreate ES modules instead of CommonJS modules
outputPathstringSpecify directory where results should be saved (relative to build directory)
The Options object

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.