svg-sprites/FEATURES.md

Иконки без лишней цены для приложения

@gromlab/svg-sprites превращает SVG проекта в кешируемую, типизированную систему иконок для React и Next.js. В коде остаются простые компоненты, а приложение получает преимущества спрайтов без сложной инфраструктуры.

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

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

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

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

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

   Generated-компоненты работают в Server Components, SSR и SSG без 'use client'. Подключение иконки не переносит страницу на клиент и не требует provider или дополнительной гидратации.

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

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

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

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

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

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

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

   Контуры иконок остаются во внешних SVG assets и не увеличивают chunks приложения. JavaScript отвечает за интерфейс и поведение, а графика загружается и кешируется отдельно.

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

   Во время генерации пакет автоматически подготавливает исходные SVG для интерфейса: удаляет фиксированные width и height с сохранением viewBox, преобразует fill и stroke в CSS-переменные и добавляет плавные transitions непосредственно в цветные элементы иконки. Каждую трансформацию можно настроить или отключить независимо.

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

   При генерации цвета fill и stroke автоматически преобразуются в CSS-переменные --icon-color-N. Монохромная иконка наследует currentColor, а в многоцветной каждый цвет можно менять отдельно. Темы, состояния и hover-эффекты создаются без редактирования SVG и дополнительных копий иконки.

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

    SpriteViewer рендерит все спрайты проекта в одном месте и показывает, какие иконки вошли в каждый набор и как они выглядят. Для каждой иконки видны созданные CSS-переменные и их fallback-цвета. Значения можно менять прямо в Viewer и сразу наблюдать результат. Здесь же доступны готовые примеры подключения через React, <svg><use>, <img> и CSS.

11. От нативного HTML до Next.js

    В основе остаётся обычный SVG-спрайт, который можно использовать даже без фреймворка и сборщика. Для React и Next.js пакет генерирует типизированные компоненты и поддерживает Vite, Webpack 5 и Turbopack. Список готовых интеграций будет расширяться новыми фреймворками.

12. Чистый Git

    Generated-файлы автоматически исключаются из Git и не засоряют историю, pull requests и код проекта. В репозитории остаются только исходные SVG и конфигурация, а локально и в CI спрайты, компоненты и типы заново создаются через prebuild.

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

    @gromlab/svg-sprites выполняет всю работу на этапе генерации и остаётся в devDependencies. Compiler и CLI не попадают в клиентское приложение: после сборки остаются только локальный типизированный компонент и внешний SVG-файл.