vite-plugin-single-image-format is a Vite/Rollup plugin that converts every raster asset in your build to a single output format – webp, png or avif. It can optionally re‑compress images that are already in the target format and automatically rewrites all
vite-plugin-single-image-format is a Vite/Rollup plugin that converts every raster asset in your build to a single output format – webp, pngoravif. It can optionally re-compress images that are already in the target format and automatically rewrites all references in HTML/CSS/JS (including JS output chunks, e.g. new URL('./img.png', import.meta.url)). It can also add or correct intrinsic width/height on tags in generated HTML, and normalizes in to match the actual format of srcset entries (e.g. image/webp), removing incorrect/duplicate type attributes.
`ts // vite.config.ts import { defineConfig } from 'vite'; import singleImageFormat from 'vite-plugin-single-image-format';
export default defineConfig({ plugins: [ singleImageFormat({ format: 'avif', // 'webp' | 'png' | 'avif' (default: 'webp') reencode: true, // also re-compress files already in the target format htmlSizeMode: 'add-only', // 'off' | 'add-only' | 'overwrite' (default: 'add-only') hashInName: true, // add content-hash to filename (e.g. name-.avif) hashLength: 8, // length of the hash prefix (default: 8) avif: { quality: 60, speed: 5 }, }), ], });
`
HTML post-processing
- Adds or corrects intrinsic width/height on (see htmlSizeMode). - Normalizes in based on the real extensions in srcset: - Replaces an incorrect type if present, or adds it if missing. - Works automatically; no extra options required.
Example:
`html
`
> Note: If
srcset entries remain in their original format (e.g. via ?imgfmt=keep or when converting is skipped), the type will reflect that format.
Options
| Field | Type | Default | Description | |:--------------:|:--------------------------------------------------------------------:|:------------:|:--------------------------------------------------------------------------| | format | 'webp' | 'png' | 'avif' | 'webp' | Output image format after build. | | reencode | boolean | false | Re-compress files already in the target format. | | htmlSizeMode | 'off' | 'add-only' | 'overwrite' | 'add-only' | Controls writing intrinsic width/height to in generated HTML. | | hashInName | boolean | false | Insert content hash into file name (name-.); updates refs. Passthrough images are also hashed. Assets with ?imgfmt=keep remain unchanged. | | hashLength | number | 8 | Length of hex SHA-256 prefix used as (range: 1–64). | | webp | Sharp WebpOptions | see defaults | Options forwarded to sharp().webp(). | | png | Sharp PngOptions | see defaults | Options forwarded to sharp().png(). | | avif | Sharp AvifOptions | see defaults | Options forwarded to sharp().avif(). |
?imgfmt=keep You can prevent conversion/renaming per image by appending a query flag to its reference. The asset will pass through unchanged, but dimensions will still be collected (when possible) for HTML sizing.`html
`
Notes
- When
hashInName is enabled, assets marked with ?imgfmt=keep are left as-is (the flag is removed from references in final code). - Passthrough case (already in target format and reencode: false) will still receive a hashed filename and updated references when hashInName: true. - Works for references found in generated JS chunks as well (e.g. URLs produced via import.meta.url).
> Tip: You can use the flag in imports, templates, or HTML — anywhere the path is visible to Vite’s pipeline.
Content hash in filename
When hashInName: true, output names include a content hash computed from the final bytes (after conversion), e.g.:` images/banner.jpg → images/banner-3f9a2c1b.webp icons/logo.webp → icons/logo-f0c1a9b3.webp (passthrough) `
- Hash algorithm: SHA-256 (hex), truncated to
hashLength characters (default: 8). - All references in HTML/CSS/JS are updated accordingly.
Supported input formats
` png, jpg/jpeg, webp, gif, avif, heif/heic, tiff, bmp, jp2 `` > Note: AVIF/HEIF/JP2 require a libvips build with the respective decoders. Encoding AVIF requires libvips compiled with AVIF encoder support.
