rollup-plugin-image-assets

1.0.0 verified Mon Apr 27 auth: no javascript

A Rollup plugin that copies image files to a configurable output directory instead of inlining them as base64. Version 1.0.0 provides features like custom output paths and renaming with MD5 hashes. Compared to alternatives like rollup-plugin-image, this plugin avoids bundle bloat by keeping images as separate files. It is forked from rollup-plugin-image-files and is actively maintained with a simple API.

Common errors

error Error: Unexpected token (Note that you need plugins to import files that are not JavaScript) ↓

cause Rollup cannot handle image imports without the plugin.

fix

Add rollup-plugin-image-assets to your rollup config.

error TypeError: Cannot read properties of undefined (reading 'substring') ↓

cause Plugin received malformed file path or unsupported image type.

fix

Ensure image files have common extensions (png, jpg, gif, svg).

error Error: Could not resolve './image.png' from 'src/index.js' ↓

cause Plugin not installed or misconfigured.

fix

Install the plugin and add it to plugins array in rollup config.

Warnings

gotcha The plugin only emits ESM output; ensure your Rollup output format is 'esm' or compatible. ↓

fix Set output.format to 'esm' in rollup config.

deprecated Option 'output' used in older versions may be replaced; check documentation for current option name. ↓

fix Use the 'output' option as shown in Quickstart for v1.

gotcha Image paths are relative to the output directory, not the source. Ensure your HTML references correct path. ↓

fix Use plugin with 'publicPath' option if needed.

Install

npm install rollup-plugin-image-assets

yarn add rollup-plugin-image-assets

pnpm add rollup-plugin-image-assets

Imports

images

wrong

const images = require('rollup-plugin-image-assets')

correct

import images from 'rollup-plugin-image-assets'

Plugin is ESM-only; using require() will fail unless your project uses esModuleInterop.

images (default)

wrong

import { images } from 'rollup-plugin-image-assets'

correct

import images from 'rollup-plugin-image-assets'

Plugin is exported as default, not a named export.

Image source
wrong
```
const imageSrc = require('./path/to/image.png')
```
correct
```
import imageSrc from './path/to/image.png'
```
Rollup resolves image imports to strings (file URLs). CommonJS require may not work in all environments.

Quickstart

Shows basic setup: install plugin, configure output directory, and import image file resulting in a hashed URL.

// rollup.config.js
import images from 'rollup-plugin-image-assets';

export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'esm'
  },
  plugins: [
    images({
      output: 'assets/images'
    })
  ]
};

// src/index.js
import logo from './logo.png';
console.log(logo); // e.g., '/assets/images/logo_abc123.png'