unplugin-image

library0.2.1jsnpmunverified

unplugin-image is a versatile bundler plugin built on the unplugin standard, enabling seamless importing of various image formats including JPG, PNG, GIF, SVG, and WebP across different build tools. Its current stable version is `0.2.1`. The package has seen recent, frequent updates, indicating active development and a rapid release cadence for bug fixes and new features, though it remains in a `0.x.x` semantic versioning range. A key differentiator is its 'universal' nature, allowing developers to write a single plugin configuration that adapts to Vite, Rollup, Webpack, Nuxt, and esbuild, significantly reducing setup complexity for projects targeting multiple build environments. It also leverages the robust options and capabilities of the well-established `@rollup/plugin-image` under the hood.

devops

npm install unplugin-image

github ↗package ↗

INSTALL

IMPORT

SIG · UNPLUGIN-IMAGE

unplugin-image

devopsjavascriptv0.2.1

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–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

UnpluginImage

✓ import UnpluginImage from 'unplugin-image/vite'

✗ import UnpluginImage from 'unplugin-image'

The main plugin factory; replace `/vite` with `/rollup`, `/esbuild`, or `require('unplugin-image/webpack')` depending on your bundler.

ImagesType

✓ import type { ImagesType } from 'unplugin-image'

Type definition for imported image assets, useful for TypeScript projects. Added in v0.2.1.

Webpack integration

✓ require('unplugin-image/webpack')

✗ import UnpluginImage from 'unplugin-image/webpack'

For CommonJS-based Webpack (and Vue CLI) configurations, use `require` instead of `import` for the plugin.

This Vite configuration demonstrates how to integrate `unplugin-image` to process and optimize image assets, including inlining small images and specifying output paths, ensuring it runs correctly with `enforce: 'pre'`.

import { defineConfig } from 'vite'; import UnpluginImage from 'unplugin-image/vite'; export default defineConfig({ plugins: [ { ...UnpluginImage({ // Options are passed directly to @rollup/plugin-image // For example, to adjust output path or optimize images limit: 10240, // 10KB, images smaller than this will be inlined as base64 URLs dom: true, // Inject images as DOM elements for server-side rendering support outputFileName: 'assets/images/[name].[ext]', }), enforce: 'pre', // Crucial for Vite to ensure this plugin runs before other asset handlers }, ], }); // Example usage in a component: // import logo from './assets/logo.png'; // <img :src="logo" alt="Logo" />

Debug

Known issues

gotchaWhen using `unplugin-image` with Vite, it is crucial to set `enforce: 'pre'` on the plugin configuration. This ensures the plugin transforms image imports before Vite's default asset handling processes them, preventing unintended behavior or build failures.

fix

Ensure your Vite plugin configuration includes `{ ...UnpluginImage(...), enforce: 'pre' }`.

affects: >=0.1.0

gotcha`unplugin-image` requires a bundler-specific subpath import (e.g., `/vite`, `/rollup`, `/webpack`, `/esbuild`, or `/nuxt`). Importing directly from `unplugin-image` will result in a module not found error or incorrect plugin instantiation.

fix

Always use the correct subpath import for your bundler: `import UnpluginImage from 'unplugin-image/<bundler>'` or `require('unplugin-image/webpack')`.

affects: >=0.1.0

gotchaThe plugin's options are directly passed through to `@rollup/plugin-image`. Developers should consult the `@rollup/plugin-image` documentation for available configuration options, as `unplugin-image` does not introduce new specific options.

fix

Refer to the `@rollup/plugin-image` documentation for a complete list of valid options and their behavior.

affects: >=0.1.0

breakingAs a `0.x.x` version package, `unplugin-image`'s API and behavior may change in minor releases without strict adherence to semantic versioning. Future minor versions could introduce breaking changes.

fix

Pin to exact versions (`"unplugin-image": "0.2.1"`) or use caution when updating minor versions in production environments. Review changelogs for each update.

affects: >=0.1.0

gotchaFor Nuxt integration, `unplugin-image` is used as a module string in `nuxt.config.js/ts`, not a direct plugin import. Attempting to import it as a standard plugin will not work with the Nuxt module system.

fix

Configure in `nuxt.config.js/ts` as `modules: [['unplugin-image/nuxt', { /* options */ }]]`.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'unplugin-image' from '/path/to/project'

Attempting to import the plugin without specifying the bundler-specific subpath.

fix

Change the import path to include your bundler, e.g., `import UnpluginImage from 'unplugin-image/vite'`.

Error: image.js: Inlined images are not supported when output.assetFileNames is set.

Conflicting `@rollup/plugin-image` options where an `outputFileName` is set while `dom: true` or `inline` options are also enabled, causing a conflict between inlining and generating separate asset files.

fix

Either remove `outputFileName` if you intend to inline all assets or adjust `limit` to prevent inlining for images that should be separate files. Alternatively, disable `dom` or `inline` if not desired.

Image assets are not processed; Vite is serving them as raw files or default asset handling is taking over.

The `unplugin-image` plugin in Vite is not running with `enforce: 'pre'`, causing other Vite asset handlers to process images first.

fix

Add `enforce: 'pre'` to the `unplugin-image` configuration in `vite.config.ts`, e.g., `{ ...UnpluginImage(), enforce: 'pre' }`.

Upgrade

Version history

0.2.1latest on npm

Audit

Dependencies

@nuxt/kitoptionalRequired for Nuxt 3 integration.

@nuxt/schemaoptionalRequired for Nuxt 3 integration.

esbuildoptionalRequired for esbuild integration.

rollupoptionalRequired for Rollup integration.

viteoptionalRequired for Vite integration.

webpackoptionalRequired for Webpack and Vue CLI integration.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/wzc520pyfm/unplugin-image ↗

packagehttps://www.npmjs.com/package/unplugin-image ↗