🏞️ Previewly

A lightweight, fast, multi-environment generator of beautiful low-quality image placeholders.

✨ Features

• 🖼️ Generates low-quality image placeholders (LQIP) in multiple formats, including Base64, CSS, SVG and color.
• 📂 Supports decoding a wide range of image formats, with configurable output encoding. See @napi-rs/image supported formats.
• 🌐 Supports multiple environments, including server and browser.
• 🚀 Provides a simple and intuitive API for generating placeholders.
• ⚡ Optimized for performance and speed, making it suitable for production use.

📦 Installation

Node.js

Previewly requires Node.js 22.23.3 or later. You can install Previewly with its required peer dependency using npm:

$ npm install @napi-rs/image previewly

Using pnpm:

$ pnpm add @napi-rs/image previewly

Using yarn:

$ yarn add @napi-rs/image previewly

Using bun:

$ bun add @napi-rs/image previewly

Browser

You can install Previewly for browser usage with its required peer dependency using npm:

$ npm install @napi-rs/image @napi-rs/image-wasm32-wasi buffer previewly

Using pnpm:

$ pnpm add @napi-rs/image @napi-rs/image-wasm32-wasi buffer previewly

Using yarn:

$ yarn add @napi-rs/image @napi-rs/image-wasm32-wasi buffer previewly

Using bun:

$ bun add @napi-rs/image @napi-rs/image-wasm32-wasi buffer previewly

See the Installation guide for more details.

🚀 Usage

See the Usage Guide for examples of generating placeholders in Node.js and browser applications.

⚙️ Options

Previewly accepts options for image orientation, placeholder size and format, brightness, saturation, hue, transparency, and EXIF metadata.

See the API Reference for all options, defaults, and types.

⚡ Performance

Previewly was benchmarked against plaiceholder using the same input images and 100 samples per case.

| Image | Size | Previewly | Plaiceholder | Speedup | | --- | ---: | ---: | ---: | ---: | | landscape-exif.jpg | 339.19 KiB | ~73 ms | ~120 ms | 1.6× | | pexels-fabianwiktor-3470872.jpg | 798.19 KiB | ~594 ms | ~866 ms | 1.5× | | portrait-exif.jpg | 239.93 KiB | ~59 ms | ~122 ms | 2.1× | | transparent.png | 2.03 MiB | ~61 ms | ~318 ms | 5.2× |

Average results show that Previewly provides lower latency and higher throughput across all tested images.

[!NOTE] Results may vary depending on hardware, runtime version and image characteristics. See full technical results in benchmark folder.

🏆 Credits

This project is highly inspired by @joe-bell/plaiceholder.

📝 Knowledge

Other related projects for the LQIP (Low-Quality Image Placeholders) technique:

• @zouhir/lqip: The original LQIP module.
• @transitive-bullshit/lqip-modern: Modern approach to LQIP using webp and sharp.
• @axe312ger/sqip: A library for SVG-based LQIP technique.
• @woltapp/blurhash: A compact representation of a placeholder for an image.
• @evanw/thumbhash: Alternative to BlurHash with some advantages.
• @frzi/lqip-css: Demonstrating a pure CSS implementation for LQIP.

Good reading on the topic of LQIP and related techniques:

• Introducing LQIP – Low Quality Image Placeholders
• How to use SVG as a Placeholder, and Other Image Loading Techniques
• The Ultimate Low-Quality Image Placeholder Technique

🤝 Contributing

Contributions to this library are welcome! If you have any ideas for improvements or new features, please feel free to open an issue or submit a pull request. I appreciate your help in making Previewly better for everyone. Please read the CONTRIBUTING.md.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.