{"id":22929,"library":"vite-plugin-webp","title":"vite-plugin-webp","description":"A Vite plugin that converts JPEG, PNG, GIF, and AVIF images to WebP format during the build process, using the sharp library for high-performance conversion. Version 1.1.3 is the latest stable release. It supports CSS background images (with a fallback class-based approach) and JS image imports with clip (dimension-based) transformations. Key differentiator: automatic inline conversion in CSS and JS without manual WebP management, plus image clipping via filename dimensions.","status":"active","version":"1.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/luchuanqi/vite-plugin-webp","tags":["javascript","vite-plugin-webp","webp","clip","vite","sharp"],"install":[{"cmd":"npm install vite-plugin-webp","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-webp","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-webp","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime dependency for image conversion to WebP","package":"sharp","optional":true}],"imports":[{"note":"Default export only. Named import will result in undefined.","wrong":"import { webp } from 'vite-plugin-webp'","symbol":"default","correct":"import webp from 'vite-plugin-webp'"},{"note":"In CommonJS, use require and assign to a variable before using in plugins array.","wrong":"module.exports = { plugins: [webp] }","symbol":"vite.config.js (CommonJS)","correct":"const webp = require('vite-plugin-webp')"},{"note":"TypeScript works with ESM default import. Avoid mixing require and import.","wrong":"const webp = require('vite-plugin-webp');","symbol":"Plugin usage in TypeScript","correct":"import webp from 'vite-plugin-webp';\nimport { defineConfig } from 'vite';\nexport default defineConfig({ plugins: [webp()] })"}],"quickstart":{"code":"import webp from 'vite-plugin-webp';\nimport path from 'path';\n\nexport default defineConfig({\n  plugins: [\n    webp({\n      include: path.join(__dirname, 'src/pages/index'),\n      exclude: path.join(__dirname, 'src/pages/index/ignore.vue'),\n      imageType: ['.png', '.jpg'],\n      sharpOptions: { quality: 100 }\n    })\n  ]\n});","lang":"javascript","description":"Basic configuration of vite-plugin-webp in vite.config.js, showing include, exclude, imageType, and sharpOptions."},"warnings":[{"fix":"Use 'exclude' option; if you copy from the README, correct the spelling.","message":"Option name misspelled: 'declude' instead of 'exclude'. The README uses 'declude' (typo) but the actual plugin option is 'exclude'.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Use 'sharpOptions' in your config.","message":"Option 'shartOptions' is a typo in the README; the correct option is 'sharpOptions'.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Name your images with dimensions in the filename, e.g., 'image240x250.png'.","message":"Clip feature requires careful filename format: 'example240x250.png' to produce 240x250 WebP. This is not documented clearly and may cause unexpected behavior.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Set 'include' to a specific directory to limit conversion scope.","message":"The plugin only transforms images inside 'include' paths (if specified) and respects 'exclude' paths. Omitting 'include' will process all images in the project, which may slow down builds.","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run 'npm install sharp' to add sharp as a direct dependency.","cause":"sharp is not installed because it's an optional dependency.","error":"Error: Cannot find module 'sharp'"},{"fix":"Change import to 'import webp from 'vite-plugin-webp'' (without curly braces).","cause":"Using named import instead of default import.","error":"Uncaught TypeError: webp is not a function"},{"fix":"Use correct option name 'sharpOptions'.","cause":"Typo in option name 'shartOptions' instead of 'sharpOptions'.","error":"[vite] Internal server error: The plugin 'vite-plugin-webp' caused a build error: Invalid key 'shartOptions'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}