S.Gromov
bdb99ade62
- перенесены каноны и VitePress-конфиги в projects/<slug> - добавлены корневой и проектные build.ts для сборки артефактов - добавлены shared-библиотеки сборки в projects/_shared/lib - обновлены CI, Dockerfile, package.json, gitignore и README - удалена сборка frontend-агента
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-архитектуры (см. [Структура проекта](/docs/applied/project-structure), [Архитектура](/docs/basics/architecture/)). В `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/` из архитектуры проекта (→ [Архитектура](/docs/basics/architecture/)) |
|
||
| `sprites[0].name` | `icons` | Основной спрайт всегда называется `icons` |
|
||
|
||
### Трансформации
|
||
|
||
Все значения по умолчанию оставлять включёнными:
|
||
|
||
```ts
|
||
transform: {
|
||
removeSize: true,
|
||
replaceColors: true,
|
||
addTransition: true,
|
||
}
|
||
```
|
||
|
||
Явно прописывать блок `transform` не нужно — пакет применяет эти значения по умолчанию.
|
||
|
||
Отключать `replaceColors` — только для отдельного спрайта с фиксированной палитрой (например, брендовые логотипы). Делать это на уровне спрайта, не глобально.
|
||
|
||
### Режим
|
||
|
||
По умолчанию `mode: 'stack'` — не указывать явно. Переход на `symbol` требует обоснования: превью и примеры в пакете оптимизированы под `stack`.
|
||
|
||
## Дальше
|
||
|
||
- [Использование](/docs/applied/svg-sprites/svg-sprites-usage) — добавление иконок, компонент `<SvgSprite/>`, управление цветом.
|