133 lines
4.9 KiB
Markdown
133 lines
4.9 KiB
Markdown
|
---
|
|||
|
|
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/<group>/` — это слой `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. Глобальный спрайт (иконки) подключается через `<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` в корне проекта. Это канон — отклонения только по явной причине.
|
|||
|
|
|
|||
|
|
```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) — добавление иконок, компонент `<SvgSprite/>`, управление цветом.
|