unplugin-images-cls-optimizer

Erase CLS by automatically optimizing images.

• ⚡️ Automatic Dimensions: Automatically calculates and injects width and height attributes to prevent layout shifts.
• 🖼️ Blurhash Placeholders: Generates and injects a blurhash background for a smooth loading experience.
• 💤 Lazy Loading: Automatically adds loading="lazy" to images.
• 💚 Vue Support: Currently optimized for Vue applications. But I’m sure it could be adapted for other frameworks as well. Feel free to open an issue or a PR to suggest support for other frameworks.

Based on the article Erase CLS by automatically optimizing images with Vite.

Installation

pnpm add -D unplugin-images-cls-optimizer

Usage

[!NOTE]
Contributions, through issues or pull requests, to extend support for other frameworks are welcome!

Vite

// vite.config.ts
import imagesClsOptimizer from 'unplugin-images-cls-optimizer/vite'

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

How it works

This plugin scans your .vue files for <img> tags. When it finds a local image (PNG or JPG/JPEG), it:

1. Reads the image file from your public directory.
2. Calculates the image dimensions using @unpic/pixels.
3. Generates a blurhash of the image.
4. Rewrites the <img> tag with:
   • width and height attributes.
   • A style attribute containing the blurhash as a background image.
   • loading="lazy".

Sponsors

License

MIT License © 2025-PRESENT Estéban Soubiran