vite-plugin-lqip

0.0.5 verified Mon Apr 27 auth: no javascript

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.

Common errors

error Error: Cannot find module 'sharp' ↓

cause sharp is a required peer dependency but was not installed.

fix

npm install sharp

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

cause Missing module declaration for the ?lqip query suffix.

fix

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

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

cause 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 Error: Your Vite config has an unknown plugin: vite-plugin-lqip ↓

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

fix

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

Warnings

gotcha The ?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';

gotcha This 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.

deprecated Sharp 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.

gotcha TypeScript 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.

gotcha The 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.

Install

npm install vite-plugin-lqip

yarn add vite-plugin-lqip

pnpm add vite-plugin-lqip

Imports

default export (plugin)
wrong
```
const lqip = require('vite-plugin-lqip')
```
correct
```
import lqip from '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

wrong

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

correct

declare module '*?lqip' { const lqip: { lqip: string; width: number; height: number; src: string; }; export default 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
wrong
```
import { lqip } from './path/to/image.jpg'
```
correct
```
import lqip from './path/to/image.jpg?lqip'
```
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.

Quickstart

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"
    />
  );
}