@rollup/plugin-image

Плагин @rollup/plugin-image предназначен для импорта изображений напрямую в JavaScript-модули с преобразованием файлов в строки формата Data URL (base64). Основная цель — упростить работу с небольшими изображениями, исключив необходимость отдельной загрузки файлов в runtime и дополнительных HTTP-запросов.

Ключевая особенность заключается в том, что изображения становятся частью бандла и могут использоваться как обычные переменные:

  • import logo fr om './logo.png'
  • logo превращается в строку data:image/png;base64,...

Установка и подключение

Плагин устанавливается через npm:

npm install @rollup/plugin-image --save-dev

Подключение в конфигурации Rollup:

import image from '@rollup/plugin-image';

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm'
  },
  plugins: [
    image()
  ]
};

После подключения Rollup начинает обрабатывать импортируемые изображения как модули.

Механизм работы

При встрече импорта изображения плагин выполняет следующие шаги:

  1. Определяет тип файла по расширению (png, jpg, gif, svg, webp)
  2. Считывает содержимое файла
  3. Кодирует данные в base64
  4. Формирует строку Data URL вида:
data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...
  1. Возвращает модуль с экспортом этой строки

Таким образом изображение становится строковым значением внутри JavaScript-кода.

Поддерживаемые форматы

Плагин поддерживает основные форматы изображений:

  • PNG
  • JPG / JPEG
  • GIF
  • SVG
  • WEBP (в зависимости от окружения)

SVG обрабатывается как текст и также может быть преобразован в Data URL.

Использование в коде

Базовый импорт

import icon from './icon.png';

const img = document.createElement('img');
img.src = icon;

document.body.appendChild(img);

В результате icon содержит base64-строку.

Использование в CSS-in-JS

import bg from './background.jpg';

const style = document.createElement('style');

style.textContent = `
  .hero {
    background-image: url(${bg});
  }
`;

document.head.appendChild(style);

Работа с SVG

import logo from './logo.svg';

document.querySelector('#logo').src = logo;

SVG остаётся строкой и может быть встроен без дополнительных преобразований.

Особенности конфигурации

Плагин имеет минимальное количество настроек, но ключевым параметром является ограничение на встроенные файлы.

Порог встроенных файлов

import image from '@rollup/plugin-image';

export default {
  plugins: [
    image({
      lim it: 10000
    })
  ]
};

Параметр limit задаёт максимальный размер файла (в байтах), который будет преобразован в base64.

  • Если файл меньше лимита — он встраивается
  • Если больше — возвращается путь или игнорируется (в зависимости от конфигурации сборки)

Поведение при больших файлах

При увеличении размера изображений использование base64 становится неэффективным:

  • увеличивается размер JS-бандла
  • ухудшается кеширование
  • замедляется первичная загрузка

Поэтому изображения большого размера обычно выносятся в отдельные ассеты или обрабатываются другими плагинами (например, asset/resource подходом).

Совместимость с другими плагинами Rollup

@rollup/plugin-image часто используется вместе с:

  • @rollup/plugin-url — для более гибкой обработки ассетов
  • @rollup/plugin-commonjs — при работе с CommonJS-модулями
  • @rollup/plugin-node-resolve — для корректного резолва импортов

Порядок подключения влияет на результат. Обычно image ставится ближе к началу цепочки обработки ассетов.

plugins: [
  image(),
  nodeResolve(),
  commonjs()
]

Отличие от @rollup/plugin-url

Ключевое различие заключается в стратегии обработки:

  • plugin-image всегда возвращает base64 строку (при попадании под обработку)

  • plugin-url может:

    • инлайнить файлы
    • либо копировать их в выходной каталог

Таким образом plugin-image ориентирован на простоту и встроенные ресурсы, а plugin-url — на гибридный подход.

Типизация и TypeScript

Плагин поддерживает использование в TypeScript-проектах без дополнительных типов.

Пример декларации импорта:

declare module '*.png' {
  const value: string;
  export default value;
}

После этого изображения можно импортировать как строки:

import avatar from './avatar.png';

const img: HTMLImageElement = new Image();
img.src = avatar;

SVG как особый случай

SVG-файлы могут вести себя иначе, чем растровые изображения:

  • сохраняют текстовую структуру
  • могут быть модифицированы как строка
  • могут быть встроены в DOM напрямую

Пример:

import icon from './icon.svg';

document.body.innerHTML = icon;

В этом случае SVG становится частью DOM без использования <img>.

Ограничения и особенности поведения

Увеличение размера бандла

Base64 увеличивает размер данных примерно на 33%, что критично для больших изображений.

Отсутствие lazy-loading

Изображения загружаются вместе с JavaScript-бандлом, без отдельной отложенной загрузки.

Кэширование

Изображения, встроенные в JS, не кэшируются отдельно браузером, так как являются частью скрипта.

Производственные сценарии

Использование оправдано в следующих случаях:

  • иконки интерфейса
  • небольшие UI-элементы
  • декоративные изображения
  • SVG-иконки
  • компоненты дизайн-систем

Не рекомендуется использовать для:

  • фотографий
  • фоновых изображений большого размера
  • медиа-контента

Поведение в SSR и Node.js окружении

В серверных сборках plugin-image не выполняет рендеринг DOM, а возвращает строковые значения. Это делает его безопасным для использования в SSR-конфигурациях Rollup.

Пример:

import logo from './logo.png';

export function render() {
  return `<img src="${logo}" />`;
}

Влияние на производительность сборки

На этапе сборки плагин выполняет операции:

  • чтение файлов с диска
  • преобразование в base64
  • генерацию JS-кода

При большом количестве изображений возможны:

  • увеличение времени сборки
  • рост потребления памяти

Оптимизация достигается через фильтрацию по limit и использование альтернативных плагинов для ассетов.

Практическая архитектура использования

Типичная схема применения:

  • plugin-image для мелких ассетов
  • plugin-url для средних файлов
  • отдельная обработка крупных медиа через asset pipeline

Такой подход позволяет балансировать между скоростью загрузки и размером бандла.

Интеграция в UI-компоненты

Пример использования в компонентной архитектуре:

import checkIcon from './check.png';

export function Button() {
  const btn = document.createElement('button');
  btn.innerHTML = `<img src="${checkIcon}" /> OK`;
  return btn;
}

Изображение становится частью компонента без внешних зависимостей.

Поведение при tree-shaking

Так как импорт изображения преобразуется в строку, Rollup может учитывать его как статический ресурс. Однако само изображение уже включено в итоговый код, поэтому tree-shaking влияет только на факт использования переменной, но не на размер base64-данных, если импорт сохранён.

Типичные ошибки использования

  • подключение больших изображений через image-плагин
  • отсутствие лимита limit
  • использование в проектах с критичной производительностью загрузки
  • дублирование одинаковых изображений в разных модулях

Роль в современной сборке Rollup

Плагин остаётся нишевым инструментом для простых сценариев работы с изображениями. Его основная ценность — минимальная конфигурация и мгновенное получение Data URL без дополнительной инфраструктуры обработки ассетов.

Оглавление