Registry / devops / vite-plugin-sharp

vite-plugin-sharp

library1.6.3jsnpmunverified

A zero-config Vite plugin for compressing images at build time using sharp (JPEG/PNG/WebP/AVIF/TIFF/GIF) and SVGO (SVG). Active, stable v1.6.3 with support for Vite 4+. Works on both bundle-asset and public/ directory images. Outperforms imagemin-based alternatives by 4-5x due to libvips native bindings. Features include content-hash caching, include/exclude filters, min-ratio/size thresholds, resize without enlargement, configurable concurrency, and per-format compression settings. Transparent terminal output showing before/after sizes per file. Ships TypeScript types.

devops

npm install vite-plugin-sharp

package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-SHARP

vite-plugin-sharp

devopsjavascriptv1.6.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

default export

✓ import viteSharp from 'vite-plugin-sharp'

✗ const viteSharp = require('vite-plugin-sharp')

ESM-only; do not use require(). Use vite.config.mjs for CommonJS projects.

OptionsType (TypeScript)

✓ import type { OptionsType } from 'vite-plugin-sharp'

✗ import { OptionsType } from 'vite-plugin-sharp'

OptionsType is a type-only export; use 'import type' in TypeScript to avoid runtime errors.

ResizeConfig

✓ import type { ResizeConfig } from 'vite-plugin-sharp'

✗ import { ResizeConfig } from 'vite-plugin-sharp'

ResizeConfig is a type-only export; use 'import type' in TypeScript.

Shows full configuration: custom quality, cache disabled, size/ratio thresholds, resize, concurrency, include/exclude filters.

// vite.config.ts import { defineConfig } from 'vite'; import viteSharp from 'vite-plugin-sharp'; export default defineConfig({ plugins: [ viteSharp({ compress: { jpeg: { quality: 80 }, png: { quality: 80 }, webp: { quality: 80 }, avif: { lossless: false }, svg: { multipass: true } }, cache: false, minRatio: 0.02, minSize: 2048, resize: { width: 1920, withoutEnlargement: true }, concurrency: 4, include: /src\/assets\//, exclude: ['icon.svg'] }) ] });

Debug

Known issues

gotchaPlugin only runs during build, not dev server. No optimization in vite dev mode.

fix

Image compression is intentionally build-only; use other tools for dev-time optimization.

affects: >=1.0.0

gotchaDefault cache file location is node_modules/.vite/sharp-cache.json, which is often removed by CI or clean installs, causing full recompression every build.

fix

Set a custom cache path outside node_modules: viteSharp({ cache: '.cache/sharp.json' })

affects: >=1.0.0

breakingv1.x changed default quality for JPEG/PNG from 80 to 75 to match sharp defaults.

fix

Explicitly set compress options if you rely on previous quality values.

affects: >=1.0.0

gotchaSVG processing uses SVGO with default preset; custom SVGO config must be passed via compress.svg, not via separate plugin configuration.

fix

Use viteSharp({ compress: { svg: { multipass: true, plugins: ['preset-default'] } } })

affects: >=1.0.0

gotchaThe resize option uses withoutEnlargement: true by default, meaning small images are never upscaled even if dimensions are specified.

fix

Set resize.withoutEnlargement to false if upscaling is desired (not recommended).

affects: >=1.0.0

gotchaThe filter regex default includes .tiff extension; TIFF images are processed but may not be well-supported in web browsers.

fix

Exclude TIFF files via exclude option if not needed: viteSharp({ exclude: '\.tiff$' })

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'vite-plugin-sharp'

Package not installed or devDependencies not installed.

fix

npm install vite-plugin-sharp -D

TypeError: viteSharp is not a function

Using require() on an ESM-only module.

fix

Use import syntax: import viteSharp from 'vite-plugin-sharp', or rename vite.config.js to vite.config.mjs

Error: [vite-plugin-sharp] Failed to compress image: ... sharp: input file is too large

Image dimensions exceed sharp's memory limits (default 3GB).

fix

Reduce image size or set sharp.limitInputPixels: sharp({ limitInputPixels: false }) via compress options.

Error: Module '"vite"' does not provide an export named 'UserConfig'

Using an outdated Vite version (<4) that doesn't export UserConfig from the main module.

fix

Upgrade Vite to >=4.0.0, or import from 'vite/dist/node' (not recommended).

Upgrade

Version history

1.6.3latest on npm

Audit

Dependencies

viterequiredpeer dependency; plugin hooks into Vite's build pipeline

Agent activity

15 hits · last 30 days

node

Perplexity

Resources

packagevite-plugin-sharp ↗