Registry / devops / vite-plugin-webp

vite-plugin-webp

library1.1.3jsnpmunverified

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.

devops

npm install vite-plugin-webp

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-WEBP

vite-plugin-webp

devopsjavascriptv1.1.3

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

✓ import webp from 'vite-plugin-webp'

✗ import { webp } from 'vite-plugin-webp'

Default export only. Named import will result in undefined.

vite.config.js (CommonJS)

✓ const webp = require('vite-plugin-webp')

✗ module.exports = { plugins: [webp] }

In CommonJS, use require and assign to a variable before using in plugins array.

Plugin usage in TypeScript

✓ import webp from 'vite-plugin-webp'; import { defineConfig } from 'vite'; export default defineConfig({ plugins: [webp()] })

✗ const webp = require('vite-plugin-webp');

TypeScript works with ESM default import. Avoid mixing require and import.

Basic configuration of vite-plugin-webp in vite.config.js, showing include, exclude, imageType, and sharpOptions.

import webp from 'vite-plugin-webp'; import path from 'path'; export default defineConfig({ plugins: [ webp({ include: path.join(__dirname, 'src/pages/index'), exclude: path.join(__dirname, 'src/pages/index/ignore.vue'), imageType: ['.png', '.jpg'], sharpOptions: { quality: 100 } }) ] });

Debug

Known issues

gotchaOption name misspelled: 'declude' instead of 'exclude'. The README uses 'declude' (typo) but the actual plugin option is 'exclude'.

fix

Use 'exclude' option; if you copy from the README, correct the spelling.

affects: >=1.0

gotchaOption 'shartOptions' is a typo in the README; the correct option is 'sharpOptions'.

fix

Use 'sharpOptions' in your config.

affects: >=1.0

gotchaClip feature requires careful filename format: 'example240x250.png' to produce 240x250 WebP. This is not documented clearly and may cause unexpected behavior.

fix

Name your images with dimensions in the filename, e.g., 'image240x250.png'.

affects: >=1.0

gotchaThe 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.

fix

Set 'include' to a specific directory to limit conversion scope.

affects: >=1.0

Errors

Common errors & fixes

Error: Cannot find module 'sharp'

sharp is not installed because it's an optional dependency.

fix

Run 'npm install sharp' to add sharp as a direct dependency.

Uncaught TypeError: webp is not a function

Using named import instead of default import.

fix

Change import to 'import webp from 'vite-plugin-webp'' (without curly braces).

[vite] Internal server error: The plugin 'vite-plugin-webp' caused a build error: Invalid key 'shartOptions'

Typo in option name 'shartOptions' instead of 'sharpOptions'.

fix

Use correct option name 'sharpOptions'.

Upgrade

Version history

1.1.3latest on npm

Audit

Dependencies

sharpoptionalRuntime dependency for image conversion to WebP

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/luchuanqi/vite-plugin-webp ↗

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