vite-plugin-svg-sprite-generator

🌐 English | 🇷🇺 Русский

Современный, производительный и абсолютно независимый от сторонних библиотек (Zero Dependencies) плагин для генерации SVG-спрайтов в Vite 5, 6, 7 и 8+.

Плагин использует нативные возможности Node.js для рекурсивного обхода директорий, что гарантирует максимальную скорость работы, минимальный размер пакета и отсутствие уязвимостей в цепочке зависимостей.

🚀 Особенности

• Zero Dependencies — не тянет за собой мегабайты из node_modules (не использует fast-glob, cheerio или svgo). Работает исключительно на нативном API Node.js.
• Два режима сборки — объединение всех иконок в один файл или автоматическое разделение на отдельные спрайты на основе структуры папок.
• Поддержка Черновиков — файлы, начинающиеся с _, автоматически игнорируются.
• Умное управление атрибутами — гибкий перенос атрибутов из тега <svg> в тег <symbol> с возможностью локального форсирования через префикс !.
• Режим автоматического обновления (Watch) — мгновенно пересобирает спрайты при добавлении, изменении или удалении файлов во время разработки.
• Безопасная очистка — умный алгоритм clean удаляет только файлы текущей сборки, полностью исключая случайное удаление пользовательских SVG (например, logo.svg или favicon.svg).

📦 Установка

Для стабильной работы плагина необходима версия Node.js >= 18.5.0 (в ней появился нативный рекурсивный обход папок) и Vite >= 5.0.0.

npm install vite-plugin-svg-sprite-generator --save-dev
# или
pnpm add -D vite-plugin-svg-sprite-generator
# или
yarn add -D vite-plugin-svg-sprite-generator

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

Добавьте плагин в ваш конфигурационный файл vite.config.js:

import { defineConfig } from "vite";
import svgSprite from "vite-plugin-svg-sprite-generator";

export default defineConfig({
  plugins: [
    svgSprite({
      input: "src/icons",
      output: "dist/assets",
      mode: "single",
      clean: true,
    }),
  ],
});

⚙️ Параметры конфигурации (API)

Все параметры являются необязательными.

| Параметр | Тип | По умолчанию | Описание | | ----------------- | --------- | --------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | input | string | 'src/icons' | Путь к папке с исходными SVG-файлами (сканируется рекурсивно). | | output | string | 'dist/assets' | Путь к директории, куда будут сохранены сгенерированные спрайты. | | name | string | 'sprite.svg' | Базовое имя файла спрайта. Расширение .svg можно не указывать. | | mode | 'single' | 'folders' | 'single' | Режим группировки иконок (один общий файл или разделение по папкам). | | clean | boolean | true | Очищать старые сгенерированные спрайты перед новой сборкой. | | inheritSvgAttrs | boolean | true | Переносить ли атрибуты оригинального <svg> (кроме xmlns и id) в <symbol>. |

📂 Режимы работы (mode)

Режим single

Все SVG-файлы из папки input (включая все подпапки) собираются в один глобальный файл спрайта.

• Имя на выходе: sprite.svg (или значение из параметра name).

Режим folders

Плагин группирует иконки по первой подпапке относительно пути input.

Если ваша структура выглядит так:

src/icons/
├── editor/
│   ├── plus.svg
│   └── minus.svg
├── code/
│   ├── js.svg
│   └── ts.svg
└── flags/
    └── us.svg

На выходе в папке output сгенерируются файлы:

• sprite-editor.svg (содержит иконки plus и minus)
• sprite-code.svg (содержит иконки js и ts)
• sprite-flags.svg (содержит иконку us)

Примечание: Если задать name: "", то префикс sprite- опускается, и файлы будут именоваться точно по названию папок: editor.svg, code.svg, flags.svg. Вложенность глубже первого уровня (например, editor/ui/add.svg) всё равно попадет в спрайт первого уровня (sprite-editor.svg).

🌟 Продвинутые возможности

Скрытые SVG (Черновики)

Если вам нужно сохранить рабочие исходники или черновики иконок в папке проекта, просто добавьте символ подчеркивания _ в начало имени файла. Плагин полностью проигнорирует их при сборке:

• _plus-old.svg — игнорируется
• minus.js — игнорируется (плагин работает только с .svg)

Наследование атрибутов и локальное переопределение

По умолчанию (inheritSvgAttrs: true) все презентационные атрибуты оригинального тега <svg> (такие как viewBox, fill, stroke, stroke-width) переносятся на тег <symbol>. Атрибуты xmlns и id всегда исключаются автоматически.

Если выставить inheritSvgAttrs: false, атрибуты не наследуются, сохраняется только viewBox (если он был задан изначально).

🔥 Локальный Override (Префикс !)

Если имя файла начинается со знака !, плагин принудительно перенесет все атрибуты для этой конкретной иконки, независимо от глобального значения inheritSvgAttrs.

После генерации префикс ! автоматически удаляется из финального id символа:

• Файл: !google.svg ➔ <symbol id="google" viewBox="..." fill="...">

🪵 Логирование и обработка ошибок

Плагин спроектирован так, чтобы никогда не прерывать процесс сборки (Vite Build) из-за отсутствующих файлов или пустых директорий. Вместо падения он выводит аккуратные предупреждения (Warnings).

При успешной генерации каждого файла в консоль Vite выводится подробная информация:

[vite-plugin-svg-sprite-generator]

Создан:
sprite-editor.svg
(15 icons)