pluginImage
A plugin that optimizes images and downloads remote images.
Optimized output images do not retain or receive metadata such as EXIF, XMP, or IPTC, or ICC profiles. Orientation correction based on EXIF Orientation is applied. There is no option to preserve metadata.
See the guide for setup and examples. This page covers settings, component props, and constraints.
Table of Contents
Options
pluginImage({
useCache: true,
remoteCache: "immutable",
optimize: {
outName: "[name]-[width]x[height]",
remoteName: "remote-[index]",
layout: "constrained",
breakpoints: [320, 400, 640, 800, 1024, 1280, 1440, 1920, 2560, 2880, 3840],
resolutions: [1, 2],
aspect: undefined,
format: "inherit",
formatOptions: {},
quality: undefined,
fit: "cover",
position: "centre",
background: undefined,
},
decoding: "async",
loading: "eager",
})useCache
- Type:
boolean - Default:
true
Use caching during development and builds.
remoteCache
- Type:
"immutable" | { maxAge: number } - Default:
"immutable"
The cache policy for remote source images. "immutable" does not fetch the source at the same URL again until the cache is deleted. { maxAge } specifies an expiration time in milliseconds; after expiration, the source is revalidated with a conditional request if ETag or Last-Modified is available. This is unused when useCache: false.
optimize.outName
- Type:
string - Default:
"[name]-[width]x[height]"
The output image file name without an extension. The following dynamic output tags are available.
[name]: Source file name[width]: Output file width[height]: Output file height
optimize.remoteName
- Type:
string - Default:
"remote-[index]"
The name assigned when downloading a remote image, without an extension. It is used as [name] in optimize.outName. The following dynamic output tag is available.
[index]: Download order (starting at 1)
optimize.layout
- Type:
"constrained" | "fixed" - Default:
"constrained"
Choose how image sizes are generated for the intended display width.
"constrained": For images whose display width varies. Generates multiple sizes based onbreakpointsfor the browser to choose from."fixed": For images with a fixed display width. Multiplies the specified display dimensions by each value inresolutions.
optimize.breakpoints
- Type:
number[] | { count: number; minWidth: number; maxWidth: number } - Default:
[320, 400, 640, 800, 1024, 1280, 1440, 1920, 2560, 2880, 3840]
Responsive widths for output images. Specify an array of numbers, or a range from minWidth to maxWidth and the number of variants in count.
optimize.resolutions
- Type:
number[] - Default:
[1, 2]
Image size multipliers for layout: "fixed". For example, [1, 2] generates 200- and 400-pixel-wide variants for an image displayed at 200 pixels wide.
optimize.format
- Type:
"inherit" | "jpg" | "png" | "webp" | "avif" - Default:
"inherit"
The output image format. "inherit" uses the same format as the source image.
optimize.formatOptions
- Type:
{ jpg?: JpegOptions, png?: PngOptions, webp?: WebpOptions, avif?: AvifOptions } - Default:
{}
Compression options for each format. Supports the corresponding sharp options.
optimize.quality
- Type:
number - Default:
undefined
Output image quality. Use optimize.formatOptions for per-format settings.
optimize.aspect
- Type:
string - Default:
undefined
Output image aspect ratio. A value such as "16:9" resizes the image to that ratio.
optimize.fit
- Type:
ResizeOptions["fit"] - Default:
"cover"
Set the fitting method for sharp Resize.
- Examples:
"cover","contain","fill","inside","outside"
optimize.position
- Type:
ResizeOptions["position"] - Default:
"centre"
Set the alignment for cropping and resizing in sharp Resize.
- Examples:
"centre","top","left","right","bottom"
optimize.background
- Type:
ResizeOptions["background"] - Default:
undefined
Set the background color for sharp Resize. Primarily applies when fit is "contain".
- Examples:
"#ffffff",{r: 255, g: 255, b: 255, alpha: 0.5}
decoding
- Type:
HTMLImageElement["decoding"] - Default:
"async"
Apply the decoding attribute to generated <img> tags.
"async": Asynchronous decoding"sync": Synchronous decoding"auto": Let the browser decide
loading
- Type:
HTMLImageElement["loading"] - Default:
"eager"
Apply the loading attribute to generated <img> tags.
"eager": Load immediately on page load"lazy": Defer loading until the image enters the viewport
Image
A component that optimizes an image using a simple <img> tag.
- Supports one source image and one output format
- Automatically reads image dimensions and adds
widthandheight - Downloads remote images
Pass the settings from the plugin’s optimize object directly as props to <Image> to override them for that image. For example, use <Image src="/src/assets/photo.jpg" format="webp" quality={80} />. Do not pass an optimize={{ ... }} object.
type ImageProps = {
src: string
sizes?: string
width?: number | string
height?: number | string
alt?: string
decoding?: HTMLImageElement["decoding"]
loading?: HTMLImageElement["loading"]
} & Partial<ImageOptimize> &
React.HTMLAttributes<HTMLImageElement>Picture
A component for advanced image optimization using <picture> with <source> and <img> tags.
- Supports art directives that change the source image according to viewport width
- Supports multiple output formats with fallbacks
- Automatically reads image dimensions and adds
widthandheight - Downloads remote images
For <Picture>, also pass optimization settings directly as props to override them for that image. Specify output formats with formats rather than format. For example, use <Picture src="/src/assets/photo.jpg" formats={["webp", "inherit"]} quality={80} />. Use artDirectives to change source images according to viewport width.
type PictureProps = {
src: string
sizes?: string
width?: number | string
height?: number | string
alt?: string
decoding?: HTMLImageElement["decoding"]
loading?: HTMLImageElement["loading"]
artDirectives?: ArtDirective[]
} & Partial<ImagesOptimize> &
React.HTMLAttributes<HTMLImageElement>
type ImagesOptimize = Omit<ImageOptimize, "format"> & {
formats: ImageFormat[]
}
type ArtDirective = {
media: string
src: string
sizes?: string
width?: number | string
height?: number | string
} & Partial<ImagesOptimize>Diagnostics
If image processing fails, the build emits the following diagnostic codes.
MINISTA_IMAGE_DOWNLOAD_FAILED: Remote image fetching failedMINISTA_IMAGE_READ_FAILED: Local image is missing or could not be readMINISTA_IMAGE_METADATA_FAILED: Image dimension or format parsing failedMINISTA_IMAGE_TRANSFORM_FAILED: Sharp conversion failedMINISTA_IMAGE_CACHE_FAILED: Cache reading or writing failed
Local image diagnostics include paths relative to the project. Remote URL query parameters are omitted from diagnostic messages.