vite-imagetools

10.0.0 verified Mon Apr 27 auth: no javascript

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.

Common errors

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

cause 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'

error TypeError: imagetools is not a function ↓

cause Default import used instead of named import.

fix

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

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

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

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

cause Image import URL syntax incorrect – missing query string prefix.

fix

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

Warnings

breaking Dropped support for Node <22 and Vite <7 ↓

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

breaking Removed CommonJS support – ESM only ↓

fix Use import syntax instead of require().

deprecated deprecated function signatures for defaultDirectives (old callback style) ↓

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

gotcha Public directory excluded by default – images in public/ won't be processed ↓

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

gotcha Sharp 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).

breaking Removed rollup-plugin-imagetools standalone package; merged into vite-imagetools ↓

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

Install

npm install vite-imagetools

yarn add vite-imagetools

pnpm add vite-imagetools

Imports

imagetools

wrong

const imagetools = require('vite-imagetools')

correct

import { imagetools } from 'vite-imagetools'

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

defaultDirectives
wrong
```
import { defaultDirectives } from 'vite-imagetools'
```
correct
```
import type { ImagetoolsOptions } from 'vite-imagetools'
```
defaultDirectives is an option property, not an export. Use TypeScript type import for configuration.

URLSearchParams

wrong

import { URLSearchParams } from 'vite-imagetools'

correct

import { URLSearchParams } from 'url'

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

Quickstart

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