Настройка SVG-спрайтов

Подключение SVG-спрайтов в новом проекте.

Установка

Установить пакет:
bash
```
npm install @gromlab/svg-sprites
```
Создать svg-sprites.config.ts в корне проекта (см. Стандартный конфиг).
Создать папку входа для SVG-файлов в слое shared:
bash
```
mkdir -p src/shared/sprites/icons
```
Источники спрайтов живут в src/shared/sprites/<group>/ — это слой shared SLM-архитектуры (см. Структура проекта, Архитектура). В src/ посторонних каталогов вне слоёв не заводим.
Добавить скрипты в package.json:
json
```
{
  "scripts": {
    "sprite": "svg-sprites",
    "predev": "svg-sprites",
    "prebuild": "svg-sprites"
  }
}
```
Хуки predev и prebuild гарантируют, что спрайты и типы всегда актуальны перед запуском и сборкой.

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

text

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

Выполнить первую генерацию:
bash
```
npm run sprite
```

Подключить спрайт в layout. Глобальный спрайт (иконки) подключается через <link rel="preload"> в корневом layout — браузер загрузит файл заранее и закеширует:

tsx

// src/app/layout.tsx
import 'shared/styles/global.css'

import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'App',
  description: '',
}

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ru">
      <head>
        <link rel="preload" href="/sprites/icons.sprite.stack.svg" as="image" />
      </head>
      <body>{children}</body>
    </html>
  )
}

Локальные спрайты (если есть) подключаются аналогично в layout конкретной страницы или маршрута.

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

Файл 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.

Дальше

Использование — добавление иконок, компонент <SvgSprite/>, управление цветом.

Настройка SVG-спрайтов ​

Установка ​

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

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

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

Режим ​