Установка и настройка

Первичная настройка пакета @gromlab/svg-sprites в проекте. Выполняется один раз при заведении проекта и при смене мажорной версии пакета.

Что такое спрайты, как с ними работать и как управлять цветом — Использование.

Требования

• Node.js 18+
• React 18+

Установка

1. Установить пакет:

   npm install @gromlab/svg-sprites

2. Создать svg-sprites.config.ts в корне проекта (см. «Стандартный конфиг»).

3. Создать папку входа для SVG-файлов в слое shared:

   mkdir -p src/shared/sprites/icons

   Источники спрайтов живут в src/shared/sprites/<group>/ — это слой shared SLM-архитектуры (см. Структура проекта, Архитектура). В src/ посторонних каталогов вне слоёв не заводим.

4. Добавить скрипты в package.json:

   {
     "scripts": {
       "sprite": "svg-sprites",
       "predev": "svg-sprites",
       "prebuild": "svg-sprites"
     }
   }

   Хуки predev и prebuild гарантируют, что спрайты и типы всегда актуальны перед запуском и сборкой.

5. Добавить сгенерированные артефакты в .gitignore:

   # Сгенерированные спрайты и React-компонент
   /public/sprites/
   /src/ui/svg-sprite/

6. Выполнить первую генерацию:

   npm run sprite

Стандартный конфиг

Файл svg-sprites.config.ts в корне проекта. Это канон — отклонения только по явной причине.

// svg-sprites.config.ts
import { defineConfig } from '@gromlab/svg-sprites'

export default defineConfig({
  output: 'public/sprites',
  publicPath: '/sprites',
  react: 'src/ui/svg-sprite',
  sprites: [
    { name: 'icons', input: 'src/shared/sprites/icons' },
  ],
})

Фиксированные значения

Опция	Значение	Почему так
output	public/sprites	Единая папка статики Next.js
publicPath	/sprites	URL-путь без public/ (Next.js раздаёт public/ как /)
react	src/ui/svg-sprite	Слой ui/ из архитектуры проекта (→ Архитектура)
sprites[0].name	icons	Основной спрайт всегда называется icons

Трансформации

Все значения по умолчанию оставлять включёнными:

transform: {
  removeSize: true,
  replaceColors: true,
  addTransition: true,
}

Явно прописывать блок transform не нужно — пакет применяет эти значения по умолчанию.

Отключать replaceColors — только для отдельного спрайта с фиксированной палитрой (например, брендовые логотипы). Делать это на уровне спрайта, не глобально.

Режим

По умолчанию mode: 'stack' — не указывать явно. Переход на symbol требует обоснования: превью и примеры в пакете оптимизированы под stack.