{"id":22727,"library":"vite-plugin-lqip","title":"vite-plugin-lqip","description":"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.","status":"active","version":"0.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/drwpow/vite-plugin-lqip","tags":["javascript","lqip","sqip","image","placeholder","optimization","sharp","core web vitals","first paint","typescript"],"install":[{"cmd":"npm install vite-plugin-lqip","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-lqip","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-lqip","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used to generate the low-quality placeholder via WebP encoding.","package":"sharp","optional":false},{"reason":"This is a Vite plugin; requires Vite as a peer dependency.","package":"vite","optional":false}],"imports":[{"note":"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.","wrong":"const lqip = require('vite-plugin-lqip')","symbol":"default export (plugin)","correct":"import lqip from 'vite-plugin-lqip'"},{"note":"The type augmentation must be for the query-suffixed import (`*?lqip`), not for the package itself. Place this in a global `.d.ts` file.","wrong":"declare module 'vite-plugin-lqip' { ... }","symbol":"LQIP module type declaration","correct":"declare module '*?lqip' { const lqip: { lqip: string; width: number; height: number; src: string; }; export default lqip; }"},{"note":"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.","wrong":"import { lqip } from './path/to/image.jpg'","symbol":"LQIP import","correct":"import lqip from './path/to/image.jpg?lqip'"}],"quickstart":{"code":"// vite.config.js\nimport lqip from 'vite-plugin-lqip';\n\nexport default {\n  plugins: [lqip()],\n};\n\n// App component (React example)\nimport lqip from './path/to/image.jpg?lqip';\n\nfunction Image() {\n  return (\n    <img\n      src={lqip.src}\n      width={lqip.width}\n      height={lqip.height}\n      style={{\n        backgroundImage: `url(\"${lqip.lqip}\")`,\n        backgroundSize: 'cover',\n      }}\n      alt=\"example\"\n    />\n  );\n}","lang":"typescript","description":"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."},"warnings":[{"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';","message":"The ?lqip import cannot be combined with other query parameters like ?w=500; it will break.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Add vite-imagetools to your Vite config. Ensure vite-plugin-lqip is placed before vite-imagetools in the plugins array.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Monitor releases for breaking changes to the sharp configuration object.","message":"Sharp options in plugin config may change in future versions. The current API is experimental.","severity":"deprecated","affected_versions":"0.0.x"},{"fix":"Add the declaration shown in the README to your project's globals.d.ts.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"If sharp installation fails, see sharp's documentation for platform-specific instructions.","message":"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).","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"npm install sharp","cause":"sharp is a required peer dependency but was not installed.","error":"Error: Cannot find module 'sharp'"},{"fix":"Add the type declaration: declare module '*?lqip' { ... } in a .d.ts file.","cause":"Missing module declaration for the ?lqip query suffix.","error":"TypeScript error: Cannot find module './path/to/image.jpg?lqip' or its corresponding type declarations."},{"fix":"Use import lqip from 'vite-plugin-lqip' instead of import { lqip } from 'vite-plugin-lqip'.","cause":"Misusing the import: the plugin is a default export, not a named export.","error":"Error: The 'lqip' function is not a function. (It might be the default export, but it was imported as a named export.)"},{"fix":"Ensure the package is installed: npm i -D vite-plugin-lqip","cause":"The plugin is not installed or the import path is wrong.","error":"Error: Your Vite config has an unknown plugin: vite-plugin-lqip"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}