Registry / web-framework / vite-plugin-lqip

vite-plugin-lqip

library0.0.5jsnpmunverified

Vite plugin (v0.0.5) that generates low-quality image placeholders (LQIP) using WebP compression via sharp. It inlines a tiny base64-encoded placeholder image (<1kB) to enable instant loading and reduce layout shift. Compatible with any Vite-powered framework (React, Svelte, Vue, Astro). The plugin does not alter source images, so it can be composed with vite-imagetools for full optimization. Uses a similar technique to lqip-modern but with custom sharp options. Releases are patch-level; current version is 0.0.5. It is not yet stable (pre-v1.0). TypeScript types are included.

web-framework data

npm install vite-plugin-lqip

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-LQIP

vite-plugin-lqip

web-frameworkjavascriptv0.0.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default export (plugin)

✓ import lqip from 'vite-plugin-lqip'

✗ const lqip = require('vite-plugin-lqip')

The package provides a single default export function. While it does ship a CJS build (since v0.0.2), the recommended usage is ESM. No named exports.

LQIP module type declaration

✓ declare module '*?lqip' { const lqip: { lqip: string; width: number; height: number; src: string; }; export default lqip; }

✗ declare module 'vite-plugin-lqip' { ... }

The type augmentation must be for the query-suffixed import (`*?lqip`), not for the package itself. Place this in a global `.d.ts` file.

LQIP import

✓ import lqip from './path/to/image.jpg?lqip'

✗ import { lqip } from './path/to/image.jpg'

The import must use the `?lqip` query suffix. The imported value is a default export of an object with `lqip`, `width`, `height`, `src`. Do not destructure at import time.

Shows how to configure the plugin in vite.config.js and use the ?lqip import in a React component to render an image with an inline LQIP placeholder, reducing layout shift.

// vite.config.js import lqip from 'vite-plugin-lqip'; export default { plugins: [lqip()], }; // App component (React example) import lqip from './path/to/image.jpg?lqip'; function Image() { return ( <img src={lqip.src} width={lqip.width} height={lqip.height} style={{ backgroundImage: `url("${lqip.lqip}")`, backgroundSize: 'cover', }} alt="example" /> ); }

Debug

Known issues

gotchaThe ?lqip import cannot be combined with other query parameters like ?w=500; it will break.

fix

Use separate imports for LQIP and for imagetools transformations: import lqip from './image.jpg?lqip'; import srcSet from './image.jpg?w=500;700&format=webp';

affects: >=0.0.1

gotchaThis plugin does not modify the source image; it only generates the LQIP. If you want optimized images (resizing, format conversion), you must add vite-imagetools separately.

fix

Add vite-imagetools to your Vite config. Ensure vite-plugin-lqip is placed before vite-imagetools in the plugins array.

affects: >=0.0.1

deprecatedSharp options in plugin config may change in future versions. The current API is experimental.

fix

Monitor releases for breaking changes to the sharp configuration object.

affects: 0.0.x

gotchaTypeScript users must add a module declaration for '*?lqip' in a global .d.ts file, otherwise the import will not be recognized by the compiler.

fix

Add the declaration shown in the README to your project's globals.d.ts.

affects: >=0.0.1

gotchaThe plugin relies on the sharp binary, which may require native compilation. Ensure your environment has the necessary build tools (e.g., for ARM64 or Alpine Linux).

fix

If sharp installation fails, see sharp's documentation for platform-specific instructions.

affects: >=0.0.1

Errors

Common errors & fixes

Error: Cannot find module 'sharp'

sharp is a required peer dependency but was not installed.

fix

npm install sharp

TypeScript error: Cannot find module './path/to/image.jpg?lqip' or its corresponding type declarations.

Missing module declaration for the ?lqip query suffix.

fix

Add the type declaration: declare module '*?lqip' { ... } in a .d.ts file.

Error: The 'lqip' function is not a function. (It might be the default export, but it was imported as a named export.)

Misusing the import: the plugin is a default export, not a named export.

fix

Use import lqip from 'vite-plugin-lqip' instead of import { lqip } from 'vite-plugin-lqip'.

Error: Your Vite config has an unknown plugin: vite-plugin-lqip

The plugin is not installed or the import path is wrong.

fix

Ensure the package is installed: npm i -D vite-plugin-lqip

Upgrade

Version history

0.0.5latest on npm

Audit

Dependencies

sharprequiredUsed to generate the low-quality placeholder via WebP encoding.

viterequiredThis is a Vite plugin; requires Vite as a peer dependency.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/drwpow/vite-plugin-lqip ↗

packagehttps://www.npmjs.com/package/vite-plugin-lqip ↗