Registry / devops / vite-imagetools

vite-imagetools

library10.0.0jsnpmunverified

A Vite plugin that transforms images at compile time using import directives, powered by sharp. Current stable version is 10.0.0, released with regular patch updates. Key differentiators include URL-based query directives for resizing, format conversion, metadata removal, and srcset generation, all optimized for Vite's build pipeline. It ships TypeScript types and requires Node >=22.0.0 and Vite >=7.0.0 as peer dependencies.

devops

npm install vite-imagetools

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-IMAGETOOLS

vite-imagetools

devopsjavascriptv10.0.0

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.

imagetools

✓ import { imagetools } from 'vite-imagetools'

✗ const imagetools = require('vite-imagetools')

ESM-only; CommonJS require() will fail. Use named import.

defaultDirectives

✓ import type { ImagetoolsOptions } from 'vite-imagetools'

✗ import { defaultDirectives } from 'vite-imagetools'

defaultDirectives is an option property, not an export. Use TypeScript type import for configuration.

URLSearchParams

✓ import { URLSearchParams } from 'url'

✗ import { URLSearchParams } from 'vite-imagetools'

URLSearchParams is a Node.js built-in, not from the plugin.

Configures the imagetools plugin with default directives, include/exclude patterns, and metadata removal. Shows how to import images with query parameters.

import { defineConfig } from 'vite' import { imagetools } from 'vite-imagetools' export default defineConfig({ plugins: [ imagetools({ defaultDirectives: (url) => { if (url.searchParams.has('spotify')) { return new URLSearchParams({ tint: 'ffaa22' }) } return new URLSearchParams() }, exclude: 'public/**/*', include: /\.(heif|avif|jpeg|jpg|png|tiff|webp|gif)(\?.*)?$/, removeMetadata: true }) ] }) // In your components: import Image from 'example.jpg?w=400&h=300&format=webp' console.log(Image) // Transformed image path/object

Debug

Known issues

breakingDropped support for Node <22 and Vite <7

fix

Upgrade Node to >=22 and Vite to >=7.

affects: >=10.0.0

breakingRemoved CommonJS support – ESM only

fix

Use import syntax instead of require().

affects: >=5.0.0

deprecateddeprecated function signatures for defaultDirectives (old callback style)

fix

Use URLSearchParams or (url: URL) => URLSearchParams.

affects: >=7.0.0

gotchaPublic directory excluded by default – images in public/ won't be processed

fix

Override exclude option if you need to transform images in public/.

affects: >=4.0.0

gotchaSharp must be installed and compatible – errors on unsupported platforms

fix

Ensure sharp is installed and your platform is supported (Windows/Linux/macOS with Node >=22).

affects: >=1.0.0

breakingRemoved rollup-plugin-imagetools standalone package; merged into vite-imagetools

fix

Use vite-imagetools for both Vite and Rollup (same plugin works with both).

affects: >=6.0.0

Errors

Common errors & fixes

Cannot find module 'vite-imagetools' or its corresponding type declarations.

Missing installation or incorrect import path (e.g., require() for ESM-only package).

fix

Run: npm install --save-dev vite-imagetools
Then use import { imagetools } from 'vite-imagetools'

TypeError: imagetools is not a function

Default import used instead of named import.

fix

Change to: import { imagetools } from 'vite-imagetools'

Error: The 'sharp' module is not installed or is not compatible with the current platform.

Sharp needs to be installed as a peer dependency (automatically installed with imagetools) but might fail on certain platforms.

fix

Reinstall sharp: npm install sharp
If platform not supported, consider using a Docker image or alternative.

Expected '?' at position 10 but found 'w'

Image import URL syntax incorrect – missing query string prefix.

fix

Use: import Image from 'example.jpg?w=400' (note the '?').

Upgrade

Version history

10.0.0latest on npm

Audit

Dependencies

viterequiredpeer dependency for plugin integration

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/JonasKruckenberg/imagetools ↗

packagehttps://www.npmjs.com/package/vite-imagetools ↗