vite-plugin-optimize-images

A Vite plugin that makes your build's images smaller, automatically. No config required to get started, no changes to your source files, and no separate compression step to remember before every commit.

Documentation and live demo

What this does

When Vite builds your site, it copies your images into the dist folder as they are. This plugin re-compresses those copies on the way out using sharp for PNG, JPEG and WebP and SVGO for SVG, so the images you actually ship end up smaller than the ones you started with. That includes images in Vite's public folder, which Vite copies as they are.

A few things this plugin is careful about, so it's safe to just turn on:

• Your original files are never touched. Only the copies written to dist/ get re-encoded. Nothing in your project or Git history changes.
• Only images that actually ship get processed. If an image never makes it into your build output, this plugin never looks at it. Files in public are read from there and only their copies in dist/ are rewritten.
• You never end up with a bigger file. If re-compressing an image wouldn't save meaningful space, the original is kept instead (see minSavings below).

Add the plugin, build your site the way you normally would, and your images come out smaller. That's the whole idea.

Install

npm install --save-dev @binarynoir/vite-plugin-optimize-images

Usage

// vite.config.ts
import { defineConfig } from "vite";
import { optimizeImagesPlugin } from "@binarynoir/vite-plugin-optimize-images";

export default defineConfig({
  plugins: [optimizeImagesPlugin()],
});

That's it — .png, .jpg/.jpeg, .webp and .svg files in your build output, including those copied from public, get optimized automatically. Run a build with VITE_OPTIMIZE_VERBOSE-style visibility by passing verbose: true (see below) to see what was optimized and by how much.

Options

Option	Default	Description
minSize	10240	Minimum source size (bytes) before an image is considered for optimization (10 KiB).
minSavings	1024	Minimum bytes an optimization must save before it's applied (1 KiB).
png	—	sharp PNG encode options override.
jpeg	—	sharp JPEG encode options override.
webp	—	sharp WebP encode options override.
svg	—	SVGO options override.
public	true	Also optimize the dist/ copies of images from Vite's public directory.
verbose	false	Log progress and per-file savings to the console.

Defaults, before any override:

{
  png: { quality: 80, compressionLevel: 9, adaptiveFiltering: true },
  jpeg: { quality: 85, progressive: true, mozjpeg: true },
  webp: { quality: 85 },
  svg: { multipass: true },
}

optimizeImagesPlugin({
  minSize: 5 * 1024,
  minSavings: 512,
  jpeg: { quality: 75 },
  verbose: true,
});

Why not vite-plugin-imagemin / vite-imagetools / etc.?

Those are great, more general options if you want format conversion, resizing, or a wider codec set. This plugin is intentionally small: it re-encodes the formats sharp and SVGO handle well, only ever operates on what's already in the build output (so it composes cleanly with any other asset pipeline you have), and never risks producing a larger file than it started with.

Releasing

Releases are tag-triggered. To ship a new version, from a clean main that's in sync with origin/main:

npm run release:patch   # or release:minor / release:major

This runs typecheck/lint/test/build locally, then npm version <bump> (bumps package.json, commits, and creates a matching vX.Y.Z tag) and git push --follow-tags. Pushing that tag triggers .github/workflows/release.yml, which re-runs the checks, publishes to npm (with provenance), and creates a GitHub release with auto-generated notes.

For a prerelease or an explicit version, use npm run release -- <arg> (e.g. npm run release -- 1.2.3 or npm run release -- prerelease) — see npm version for the full list of accepted values.

This requires an NPM_TOKEN repository secret (an npm automation token with publish access) — set it under Settings → Secrets and variables → Actions. First time publishing this package? See PUBLISHING.md.

License

MIT

---

Feedback and support

Bug reports, feature requests and questions are all welcome. Please open them on this project's GitHub issue tracker:

• Found a bug? Report it. Include your version and the steps to reproduce it.
• Have an idea? Request a feature. Tell us what you are trying to do.
• Something else? Browse open issues to see if it has already been raised.

Pull requests are welcome too.

More from BinaryNoir

Optimize Images is one of a family of open-source tools from BinaryNoir.

Pairs well with Optimize Images

• Image Fallback: a placeholder instead of a failed build

New: Blog: posts anywhere, a main blog and section blogs, with RSS feeds

See them all: VitePress plugins, Vite plugins, editor extensions and command-line tools, with documentation and live demos, at binarynoir.tech.

Author

John Smith III, BinaryNoir. Thanks to all contributors and users for their support and feedback.