--- title: Настройка SVG-спрайтов description: Подключение SVG-спрайтов в новом проекте. keywords: [svg-sprites, установка, настройка, config, пакет, "@gromlab/svg-sprites", svg-sprites.config.ts] --- # Настройка SVG-спрайтов Подключение SVG-спрайтов в новом проекте. ## Установка 1. Установить пакет: ```bash npm install @gromlab/svg-sprites ``` 2. Создать `svg-sprites.config.ts` в корне проекта (см. [Стандартный конфиг](#стандартныи-конфиг)). 3. Создать папку входа для SVG-файлов в слое `shared`: ```bash mkdir -p src/shared/sprites/icons ``` Источники спрайтов живут в `src/shared/sprites//` — это слой `shared` SLM-архитектуры (см. [Структура проекта](../project-structure.md), [Архитектура](../../basics/architecture/index.md)). В `src/` посторонних каталогов вне слоёв не заводим. 4. Добавить скрипты в `package.json`: ```json { "scripts": { "sprite": "svg-sprites", "predev": "svg-sprites", "prebuild": "svg-sprites" } } ``` Хуки `predev` и `prebuild` гарантируют, что спрайты и типы всегда актуальны перед запуском и сборкой. 5. Добавить сгенерированные артефакты в `.gitignore`: ```text # Сгенерированные спрайты и React-компонент /public/sprites/ /src/ui/svg-sprite/ ``` 6. Выполнить первую генерацию: ```bash npm run sprite ``` 7. Подключить спрайт в layout. Глобальный спрайт (иконки) подключается через `` в корневом 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 ( {children} ) } ``` Локальные спрайты (если есть) подключаются аналогично в layout конкретной страницы или маршрута. ## Стандартный конфиг Файл `svg-sprites.config.ts` в корне проекта. Это канон — отклонения только по явной причине. ```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/` из архитектуры проекта (→ [Архитектура](../../basics/architecture/index.md)) | | `sprites[0].name` | `icons` | Основной спрайт всегда называется `icons` | ### Трансформации Все значения по умолчанию оставлять включёнными: ```ts transform: { removeSize: true, replaceColors: true, addTransition: true, } ``` Явно прописывать блок `transform` не нужно — пакет применяет эти значения по умолчанию. Отключать `replaceColors` — только для отдельного спрайта с фиксированной палитрой (например, брендовые логотипы). Делать это на уровне спрайта, не глобально. ### Режим По умолчанию `mode: 'stack'` — не указывать явно. Переход на `symbol` требует обоснования: превью и примеры в пакете оптимизированы под `stack`. ## Дальше - [Использование](./svg-sprites-usage.md) — добавление иконок, компонент ``, управление цветом.