{"id":22563,"library":"vite-imagetools","title":"vite-imagetools","description":"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.","status":"active","version":"10.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/JonasKruckenberg/imagetools","tags":["javascript","resize-images","responsive-images","vite","image","vite-plugin","typescript"],"install":[{"cmd":"npm install vite-imagetools","lang":"bash","label":"npm"},{"cmd":"yarn add vite-imagetools","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-imagetools","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency for plugin integration","package":"vite","optional":false}],"imports":[{"note":"ESM-only; CommonJS require() will fail. Use named import.","wrong":"const imagetools = require('vite-imagetools')","symbol":"imagetools","correct":"import { imagetools } from 'vite-imagetools'"},{"note":"defaultDirectives is an option property, not an export. Use TypeScript type import for configuration.","wrong":"import { defaultDirectives } from 'vite-imagetools'","symbol":"defaultDirectives","correct":"import type { ImagetoolsOptions } from 'vite-imagetools'"},{"note":"URLSearchParams is a Node.js built-in, not from the plugin.","wrong":"import { URLSearchParams } from 'vite-imagetools'","symbol":"URLSearchParams","correct":"import { URLSearchParams } from 'url'"}],"quickstart":{"code":"import { defineConfig } from 'vite'\nimport { imagetools } from 'vite-imagetools'\n\nexport default defineConfig({\n  plugins: [\n    imagetools({\n      defaultDirectives: (url) => {\n        if (url.searchParams.has('spotify')) {\n          return new URLSearchParams({ tint: 'ffaa22' })\n        }\n        return new URLSearchParams()\n      },\n      exclude: 'public/**/*',\n      include: /\\.(heif|avif|jpeg|jpg|png|tiff|webp|gif)(\\?.*)?$/,\n      removeMetadata: true\n    })\n  ]\n})\n\n// In your components:\nimport Image from 'example.jpg?w=400&h=300&format=webp'\nconsole.log(Image) // Transformed image path/object","lang":"typescript","description":"Configures the imagetools plugin with default directives, include/exclude patterns, and metadata removal. Shows how to import images with query parameters."},"warnings":[{"fix":"Upgrade Node to >=22 and Vite to >=7.","message":"Dropped support for Node <22 and Vite <7","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Use import syntax instead of require().","message":"Removed CommonJS support – ESM only","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Use URLSearchParams or (url: URL) => URLSearchParams.","message":"deprecated function signatures for defaultDirectives (old callback style)","severity":"deprecated","affected_versions":">=7.0.0"},{"fix":"Override exclude option if you need to transform images in public/.","message":"Public directory excluded by default – images in public/ won't be processed","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Ensure sharp is installed and your platform is supported (Windows/Linux/macOS with Node >=22).","message":"Sharp must be installed and compatible – errors on unsupported platforms","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use vite-imagetools for both Vite and Rollup (same plugin works with both).","message":"Removed rollup-plugin-imagetools standalone package; merged into vite-imagetools","severity":"breaking","affected_versions":">=6.0.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 --save-dev vite-imagetools\nThen use import { imagetools } from 'vite-imagetools'","cause":"Missing installation or incorrect import path (e.g., require() for ESM-only package).","error":"Cannot find module 'vite-imagetools' or its corresponding type declarations."},{"fix":"Change to: import { imagetools } from 'vite-imagetools'","cause":"Default import used instead of named import.","error":"TypeError: imagetools is not a function"},{"fix":"Reinstall sharp: npm install sharp\nIf platform not supported, consider using a Docker image or alternative.","cause":"Sharp needs to be installed as a peer dependency (automatically installed with imagetools) but might fail on certain platforms.","error":"Error: The 'sharp' module is not installed or is not compatible with the current platform."},{"fix":"Use: import Image from 'example.jpg?w=400' (note the '?').","cause":"Image import URL syntax incorrect – missing query string prefix.","error":"Expected '?' at position 10 but found 'w'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}