esbuild-plugin-imagemin

1.0.1 verified Fri May 01 auth: no javascript

An esbuild plugin that automatically minifies images (PNG, JPG, GIF, SVG) during the build process using imagemin. Version 1.0.1 is the latest stable release, supports both CJS and ESM imports, and provides TypeScript type definitions. It bundles several popular imagemin plugins (mozjpeg, gifsicle, pngquant, svgo) by default, with options to disable individual ones, configure their options, or add custom imagemin plugins. This plugin differentiates itself by integrating seamlessly with esbuild's build pipeline, requiring no additional loaders or configuration beyond adding the plugin.

Common errors

error Error: Cannot find module 'imagemin' ↓

cause Missing imagemin dependency (peer dependency not auto-installed in some npm versions).

fix

npm install imagemin

error TypeError: imageminPlugin is not a function ↓

cause Calling the plugin without parentheses: plugins: [imageminPlugin] instead of plugins: [imageminPlugin()].

fix

Change to imageminPlugin()

error Error: Is a directory ↓

cause The plugin may attempt to process a directory path incorrectly if glob patterns are used.

fix

Ensure entry points are files, not directories.

Warnings

gotcha The plugin is a function that must be called — passing the function reference directly will not work. ↓

fix Use imageminPlugin() instead of imageminPlugin in the plugins array.

breaking Version 1.0.0 changed the default plugins list; previous versions may have used different defaults. ↓

fix Review default plugins and use disableDefaultPlugins if needed.

gotcha The plugin only minifies images referenced via import/require in the bundle — it does not handle all image files automatically unless they are part of the build graph. ↓

fix Ensure images are imported in your source files.

deprecated The package previously did not ship TypeScript types; type definitions were added in v1.0.1. ↓

fix Upgrade to v1.0.1 to get built-in TypeScript support.

Install

npm install esbuild-plugin-imagemin

yarn add esbuild-plugin-imagemin

pnpm add esbuild-plugin-imagemin

Imports

default

wrong

const imageminPlugin = require('esbuild-plugin-imagemin')

correct

import imageminPlugin from 'esbuild-plugin-imagemin'

ESM default import is preferred; CJS require also works.

ImageminPluginOptions

import type { ImageminPluginOptions } from 'esbuild-plugin-imagemin'

TypeScript type import, available when using TS.

esbuild plugin array entry
wrong
```
plugins: [imageminPlugin]
```
correct
```
plugins: [imageminPlugin()]
```
The plugin is a function that returns a plugin object; call it before passing to plugins array.

Quickstart

Shows basic setup of esbuild with the imagemin plugin enabled, using ESM imports and async build.

import esbuild from 'esbuild';
import imageminPlugin from 'esbuild-plugin-imagemin';

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [imageminPlugin()],
});