svg-sprites/README_RU.md

@gromlab/svg-sprites

🇬🇧 English | 🇷🇺 Русский

@gromlab/svg-sprites — генератор SVG-спрайтов для современных веб-приложений. Он собирает выбранные SVG-иконки в один или несколько внешних кешируемых спрайтов и подготавливает их для использования в интерфейсе.

Для vanilla-приложений с Vite/Webpack пакет создаёт нативный типизированный Web Component, а для React и Next.js — React-компонент. SVG во всех случаях остаётся отдельным кешируемым asset.

SVG-спрайт так же прост, как обычная SVG-иконка

Для всего спрайта генерируется один типизированный React-компонент. Выберите иконку через icon, а редактор покажет автокомплит всех доступных имён.

<AppIcon icon="search" width={24} height={24} />

Компонент принимает привычные SVG-атрибуты: размеры, color, className, style, aria-* и обработчики событий. Если нужен внешний контейнер, добавьте wrapped.

<AppIcon icon="search" wrapped className="iconWrapper" />

В приложении не приходится работать со спрайтом напрямую. Вы используете его так же, как обычную SVG-иконку, но получаете один компонент, автокомплит и TypeScript-проверку всех имён.

AI-friendly из коробки

@gromlab/svg-sprites сразу рассчитан на работу с AI-агентами. Подключите готовый skill и поручите агенту настройку, миграцию или диагностику без длинных инструкций и ручного изучения документации.

🇷🇺 Скачать AI skill (на русском)

🇬🇧 Скачать AI skill (на английском)

От SVG до компонента за три шага

Основной пример использует Next.js App Router и Turbopack.

1. Укажите нужные иконки

Создайте папки для исходных иконок и спрайта:

assets/
├── app-icons/
│   └── svg-sprite.config.json
└── svg-icons/
    ├── search.svg
    └── settings.svg

Создайте конфигурацию спрайта:

{
  "mode": "next@app/turbopack",
  "name": "app",
  "input": "../svg-icons/**/*.svg"
}

input поддерживает пути к папкам, отдельным SVG и glob-шаблоны.

2. Добавьте генерацию

{
  "scripts": {
    "sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
    "predev": "npm run sprites",
    "prebuild": "npm run sprites"
  }
}

Создайте точку входа для сгенерированного API:

// assets/app-icons/index.ts
export * from './.svg-sprite/index.js'

Первый запуск:

npm run sprites

Пакет создаст AppIcon, TypeScript-типы и отдельный SVG-спрайт.

3. Используйте как обычную иконку

// app/page.tsx
import { AppIcon } from '../assets/app-icons'

export default function SearchButton() {
  return (
    <button type="button">
      <AppIcon icon="search" width={20} height={20} />
      Найти
    </button>
  )
}

Это Server Component. Для иконки не нужны provider, 'use client' или ручная сборка URL.

Типизированный React-компонент с автокомплитом

Каждый спрайт получает собственный готовый компонент. Свойство icon формируется из реальных имён SVG, поэтому редактор показывает точный список доступных иконок, а TypeScript сразу обнаруживает опечатки.

<AppIcon icon="search" />  // доступная иконка
<AppIcon icon="serach" />  // ошибка TypeScript

После добавления новой SVG-иконки и повторной генерации её имя автоматически появляется в типах и автокомплите. Не нужно вручную поддерживать компоненты, union-типы или реестр имён.

Next.js App Router и SSR из коробки

Generated-компоненты работают в Server Components, SSR и SSG без 'use client'.

Подключение иконки не переносит страницу на клиент, не требует provider и не создаёт дополнительную границу гидратации.

Один и тот же компонент можно использовать в page.tsx, layout.tsx, серверных и клиентских компонентах.

Множественные спрайты вместо одного глобального

Проект не ограничен одним набором иконок. Создавайте независимые спрайты для общих элементов, отдельных страниц и крупных UI-модулей.

<AppIcon icon="search" />
<AnalyticsIcon icon="chart" />
<EditorIcon icon="bold" />

Каждый набор получает собственный типизированный компонент и SVG asset, поэтому разделы приложения не несут иконки, которые им не нужны.

Каждая иконка хранится в одном экземпляре

В библиотеке исходников каждая SVG-иконка хранится в одном экземпляре и может входить в любое количество спрайтов. Общие иконки не приходится копировать между страницами и модулями: они обновляются для всех наборов из одного места.

search.svg ─┬─→ AppIcon
            ├─→ AnalyticsIcon
            └─→ EditorIcon

Спрайты разделяются ради производительности, но библиотека исходных иконок остаётся единой.

Браузерное кеширование

При стандартной конфигурации Vite, Webpack или Next.js каждый спрайт выпускается отдельным версионированным SVG-файлом.

Пока набор иконок не меняется, браузер может использовать сохранённую копию независимо от обновлений JavaScript приложения.

Изменение React-компонентов не требует повторно загружать геометрию всех иконок.

JavaScript без SVG-балласта

Контуры иконок остаются во внешних SVG assets и не увеличивают chunks приложения.

React-код   → JavaScript chunks
SVG-иконки  → отдельные SVG assets

JavaScript отвечает за интерфейс и поведение, а графика загружается и кешируется отдельно.

Трансформации SVG из коробки

Во время генерации пакет автоматически подготавливает исходные SVG для интерфейса:

• удаляет фиксированные width и height;
• сохраняет существующий viewBox;
• преобразует fill и stroke в CSS-переменные;
• добавляет плавные transitions непосредственно в цветные элементы иконки.

Каждую трансформацию можно настроить или отключить независимо.

Каждый цвет под контролем CSS

При генерации цвета fill и stroke автоматически преобразуются в CSS-переменные --icon-color-N.

Монохромная иконка наследует currentColor:

<AppIcon icon="search" color="rebeccapurple" />

В многоцветной иконке каждый цвет можно менять отдельно:

<AppIcon
  icon="user"
  style={{
    '--icon-color-1': '#2563eb',
    '--icon-color-2': '#dbeafe',
  }}
/>

Темы, состояния и hover-эффекты создаются без редактирования SVG и дополнительных копий иконки.

SpriteViewer: все спрайты на одной debug-странице

SpriteViewer рендерит все standalone, React и Next.js спрайты проекта в одном месте. Один Web Component отвечает за визуал, а React использует тонкий bridge к нему.

Для каждой иконки видны созданные CSS-переменные и их fallback-цвета. Значения можно менять прямо в Viewer и сразу наблюдать результат.

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

• React;
• <svg><use>;
• <img>;
• CSS.

Viewer подключается только к внутренней debug-странице и не становится частью generated-компонентов иконок.

Bare standalone подключает Viewer через browser script и HTML element; bundler modes используют npm entry, а React и Next.js импортируют SpriteViewer из @gromlab/svg-sprites/react.

Standalone, React и Next.js

Пакет генерирует низкоуровневые standalone-спрайты для static HTML, Vite и Webpack 5, а также типизированные React-компоненты для React и Next.js.

Чистый Git

Bundler и framework modes создают локальный .gitignore, который исключает generated-файлы и не позволяет им засорять историю, pull requests и код проекта. Bare standalone оставляет политику репозитория приложению.

В bundler и framework modes в репозитории остаются исходные SVG, конфигурация и правило .gitignore, а локально и в CI спрайты, компоненты и типы заново создаются через prebuild.

В production только иконки

Генерация полностью работает через npx, без добавления package в проект. Устанавливайте его как development dependency, только если нужны Viewer, типы конфига или программный API.

Production-компоненты используют только локальный generated-код, стили и внешний SVG-файл. Compiler и CLI не попадают в клиентское приложение, а SpriteViewer подключается отдельно только там, где нужна debug-страница.

Документация

README знакомит с возможностями проекта и показывает основной сценарий использования. Для настройки выберите руководство под свой стек.

Быстрый старт

• Bare standalone
• Standalone + Vite
• Standalone + Webpack 5
• React + Vite
• React + Webpack 5
• Next.js App Router + Turbopack
• Next.js App Router + Webpack
• Next.js Pages Router + Turbopack
• Next.js Pages Router + Webpack

Технические материалы

• Индекс документации
• Конфигурация
• Технический справочник
• Программный API

Лицензия

MIT