mirror of
https://github.com/gromlab-ru/slm-design.git
synced 2026-08-22 07:30:16 +03:00
feat: add example
This commit is contained in:
56
.opencode/skills/svg-sprites-ru/references/docs/ru/README.md
Normal file
56
.opencode/skills/svg-sprites-ru/references/docs/ru/README.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# Документация
|
||||
|
||||
Для настройки выберите guide одного exact mode. Каждый guide является
|
||||
самостоятельным документом и без изменений используется в AI skills.
|
||||
|
||||
Общий формат JSON, JavaScript и TypeScript config-файлов описан в [руководстве по конфигурации](configuration.md).
|
||||
|
||||
## Быстрый старт для consumer modes
|
||||
|
||||
| Проект | Exact mode | Guide |
|
||||
|---|---|---|
|
||||
| Static HTML или собственная публикация | `standalone` | [Bare standalone](guides/standalone.md) |
|
||||
| Vanilla + Vite | `standalone@vite` | [Standalone + Vite](guides/standalone-vite.md) |
|
||||
| Vanilla + Webpack 5 | `standalone@webpack` | [Standalone + Webpack](guides/standalone-webpack.md) |
|
||||
| React + Vite | `react@vite` | [React + Vite](guides/react-vite.md) |
|
||||
| React + Webpack 5 | `react@webpack` | [React + Webpack](guides/react-webpack.md) |
|
||||
| Vue + Vite | `vue@vite` | [Vue + Vite](guides/vue-vite.md) |
|
||||
| Vue + Webpack | `vue@webpack` | [Vue + Webpack](guides/vue-webpack.md) |
|
||||
| Nuxt + Vite | `nuxt@vite` | [Nuxt + Vite](guides/nuxt-vite.md) |
|
||||
| Nuxt + Webpack | `nuxt@webpack` | [Nuxt + Webpack](guides/nuxt-webpack.md) |
|
||||
| Svelte + Vite | `svelte@vite` | [Svelte + Vite](guides/svelte-vite.md) |
|
||||
| Svelte + Webpack | `svelte@webpack` | [Svelte + Webpack](guides/svelte-webpack.md) |
|
||||
| SvelteKit + Vite | `sveltekit@vite` | [SvelteKit + Vite](guides/sveltekit-vite.md) |
|
||||
| Angular application builder | `angular@application` | [Angular application builder](guides/angular-application.md) |
|
||||
| Angular + Webpack | `angular@webpack` | [Angular + Webpack](guides/angular-webpack.md) |
|
||||
| Astro + Vite | `astro@vite` | [Astro + Vite](guides/astro-vite.md) |
|
||||
| Solid + Vite | `solid@vite` | [Solid + Vite](guides/solid-vite.md) |
|
||||
| Solid + Webpack | `solid@webpack` | [Solid + Webpack](guides/solid-webpack.md) |
|
||||
| SolidStart + Vite | `solid-start@vite` | [SolidStart + Vite](guides/solid-start-vite.md) |
|
||||
| Preact + Vite | `preact@vite` | [Preact + Vite](guides/preact-vite.md) |
|
||||
| Preact + Webpack | `preact@webpack` | [Preact + Webpack](guides/preact-webpack.md) |
|
||||
| Qwik + Vite | `qwik@vite` | [Qwik + Vite](guides/qwik-vite.md) |
|
||||
| Lit + Vite | `lit@vite` | [Lit + Vite](guides/lit-vite.md) |
|
||||
| Lit + Webpack | `lit@webpack` | [Lit + Webpack](guides/lit-webpack.md) |
|
||||
| Alpine.js + Vite | `alpine@vite` | [Alpine.js + Vite](guides/alpine-vite.md) |
|
||||
| Alpine.js + Webpack | `alpine@webpack` | [Alpine.js + Webpack](guides/alpine-webpack.md) |
|
||||
| Next.js App Router + Turbopack | `next@app/turbopack` | [App Router + Turbopack](guides/next-app-turbopack.md) |
|
||||
| Next.js App Router + Webpack | `next@app/webpack` | [App Router + Webpack](guides/next-app-webpack.md) |
|
||||
| Next.js Pages Router + Turbopack | `next@pages/turbopack` | [Pages Router + Turbopack](guides/next-pages-turbopack.md) |
|
||||
| Next.js Pages Router + Webpack | `next@pages/webpack` | [Pages Router + Webpack](guides/next-pages-webpack.md) |
|
||||
|
||||
Все consumer guides используют один порядок:
|
||||
|
||||
1. Генерация спрайта через `npx` без добавления package в проект.
|
||||
2. Использование спрайта в приложении.
|
||||
3. Необязательное подключение Viewer для дебага и превью.
|
||||
|
||||
## Серверная генерация
|
||||
|
||||
Используйте [`standalone@server`](guides/standalone-server.md), чтобы сгенерировать на сервере или в CI/CD универсальный SVG-спрайт для всех consumer modes.
|
||||
|
||||
## Справочники
|
||||
|
||||
- [Конфигурация](configuration.md)
|
||||
- [Технический справочник](reference/technical.md)
|
||||
- [Программный API](reference/programmatic-api.md)
|
||||
@@ -0,0 +1,139 @@
|
||||
# Конфигурация
|
||||
|
||||
Каждый config-файл описывает один независимый спрайт. CLI не ищет конфиг автоматически, поэтому всегда передавайте путь явно:
|
||||
|
||||
```bash
|
||||
npx --yes @gromlab/svg-sprites path/to/svg-sprite.config.json
|
||||
```
|
||||
|
||||
## JSON
|
||||
|
||||
JSON подходит для большинства проектов и не требует локальной установки пакета:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "next@app/turbopack",
|
||||
"name": "app",
|
||||
"description": "Общие иконки приложения",
|
||||
"input": [
|
||||
"./icons",
|
||||
"../../assets/icons/**/*.svg",
|
||||
"!../../assets/icons/deprecated-*.svg"
|
||||
],
|
||||
"transform": {
|
||||
"removeSize": true,
|
||||
"replaceColors": true,
|
||||
"addTransition": true
|
||||
},
|
||||
"generatedNotice": true
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | По умолчанию | Назначение |
|
||||
|---|---|---|
|
||||
| `mode` | Нет | Exact mode, соответствующий framework и сборщику |
|
||||
| `source` | `local` | `local` для исходных SVG или `remote` для manifest от `standalone@server` |
|
||||
| `name` | Kebab-case имени каталога модуля; для `svg-sprite` и `svg-sprites` — имени родительского каталога | Имя спрайта; в modes с компонентом также задаёт имя компонента и типов |
|
||||
| `description` | Нет | Описание для типов и Viewer |
|
||||
| `input` | `./icons` | Каталог, SVG-файл, glob-шаблон или массив источников |
|
||||
| `transform` | Все включены | Настройки подготовки SVG |
|
||||
| `generatedNotice` | `true` | Вид предупреждения в generated-файлах |
|
||||
|
||||
Пути и glob-шаблоны в `input` считаются от каталога config-файла. Паттерн с префиксом `!` исключает совпадения.
|
||||
|
||||
## Удалённо собранный спрайт
|
||||
|
||||
Consumer config для server manifest содержит только mode, source и input:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "react@vite",
|
||||
"source": "remote",
|
||||
"input": "https://assets.example/releases/app/svg-sprite.manifest.json"
|
||||
}
|
||||
```
|
||||
|
||||
`input` принимает один HTTP(S) URL или локальный путь к manifest. Имя, описание,
|
||||
transforms и generated notice берутся из manifest. Генератор скачивает и проверяет
|
||||
подходящий SVG profile, после чего adapter создаёт обычные локальные компоненты,
|
||||
типы и asset для сборщика.
|
||||
|
||||
## Серверная сборка
|
||||
|
||||
`standalone@server` объединяет local paths/globs и HTTP(S) SVG descriptors:
|
||||
|
||||
```js
|
||||
export default {
|
||||
mode: 'standalone@server',
|
||||
name: 'app',
|
||||
input: [
|
||||
'./icons/**/*.svg',
|
||||
{
|
||||
name: 'remote-logo',
|
||||
url: 'https://assets.example/logo.svg',
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
Mode создаёт два content-addressed SVG profiles и `svg-sprite.manifest.json`.
|
||||
`sha256` у HTTP input необязателен; если он указан, это должен быть ожидаемый
|
||||
64-символьный hexadecimal SHA-256 digest, по которому сборка проверит полученные байты.
|
||||
|
||||
## JavaScript
|
||||
|
||||
JavaScript-конфиг экспортирует обычный объект по умолчанию:
|
||||
|
||||
```js
|
||||
export default {
|
||||
mode: 'react@vite',
|
||||
name: 'icons',
|
||||
input: './icons',
|
||||
}
|
||||
```
|
||||
|
||||
Передайте CLI путь к `.js`-файлу так же, как к JSON:
|
||||
|
||||
```bash
|
||||
npx --yes @gromlab/svg-sprites path/to/svg-sprite.config.js
|
||||
```
|
||||
|
||||
## TypeScript
|
||||
|
||||
Для проверки конфига TypeScript установите пакет как dev dependency:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Используйте `defineSpriteConfig`:
|
||||
|
||||
```ts
|
||||
import { defineSpriteConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default defineSpriteConfig({
|
||||
mode: 'react@vite',
|
||||
name: 'icons',
|
||||
input: './icons',
|
||||
})
|
||||
```
|
||||
|
||||
Или примените `satisfies` с type-only импортом:
|
||||
|
||||
```ts
|
||||
import type { SpriteConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default {
|
||||
mode: 'react@vite',
|
||||
name: 'icons',
|
||||
input: './icons',
|
||||
} satisfies SpriteConfig
|
||||
```
|
||||
|
||||
CLI загружает `.ts`-конфиг напрямую:
|
||||
|
||||
```bash
|
||||
npx --yes @gromlab/svg-sprites path/to/svg-sprite.config.ts
|
||||
```
|
||||
|
||||
Полный список modes, CLI-флагов, правил именования и transform-опций находится в [техническом справочнике](reference/technical.md).
|
||||
@@ -0,0 +1,91 @@
|
||||
# SVG-спрайт для Alpine.js на Vite
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в Alpine.js-приложении на Vite.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "alpine@vite",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Генератор не нужно добавлять в зависимости приложения: запускайте его через `npx`.
|
||||
|
||||
Добавьте генерацию перед запуском разработки и production-сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "vite",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "vite build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт Alpine plugin `appAlpinePlugin`, директиву `x-app-icon` и magic `$appIconHref`.
|
||||
|
||||
Создайте `assets/app-icons/index.js`:
|
||||
|
||||
```js
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Зарегистрируйте generated plugin до запуска Alpine:
|
||||
|
||||
```js
|
||||
import Alpine from 'alpinejs'
|
||||
import { appAlpinePlugin } from '../assets/app-icons/index.js'
|
||||
|
||||
Alpine.plugin(appAlpinePlugin)
|
||||
Alpine.start()
|
||||
```
|
||||
|
||||
Используйте реактивную директиву на SVG-элементе:
|
||||
|
||||
```html
|
||||
<svg
|
||||
x-data="{ iconName: 'icon-name' }"
|
||||
x-app-icon="iconName"
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style="width:24px;height:24px;color:#334155;--icon-color-2:#f59e0b"
|
||||
></svg>
|
||||
```
|
||||
|
||||
Выражение директивы возвращает имя исходного SVG без расширения. Монохромная иконка наследует `color`, а слои многоцветной иконки переопределяются через `--icon-color-N`. Vite подключает generated CSS и выпускает `sprite.svg` отдельным production asset.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице и нужен только при разработке. Установите его отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Добавьте Viewer на development-страницу:
|
||||
|
||||
```html
|
||||
<gromlab-sprite-viewer viewer-title="Иконки проекта"></gromlab-sprite-viewer>
|
||||
<script type="module" src="/src/svg-sprite-debug.js"></script>
|
||||
```
|
||||
|
||||
Создайте `src/svg-sprite-debug.js`:
|
||||
|
||||
```js
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
import spriteManifest from '../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'
|
||||
|
||||
document.querySelector('gromlab-sprite-viewer').sources = [spriteManifest]
|
||||
```
|
||||
|
||||
Запустите `npm run dev` и откройте development-страницу. Viewer не зависит от Alpine plugin.
|
||||
@@ -0,0 +1,103 @@
|
||||
# SVG-спрайт для Alpine.js на Webpack 5
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в Alpine.js-приложении на Webpack 5.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "alpine@webpack",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Генератор не нужно добавлять в зависимости приложения: запускайте его через `npx`.
|
||||
|
||||
Добавьте генерацию перед запуском разработки и production-сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "webpack serve --mode development",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "webpack --mode production"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт Alpine plugin `appAlpinePlugin`, директиву `x-app-icon` и magic `$appIconHref`.
|
||||
|
||||
Generated CSS Alpine импортируется с query `?inline`. Добавьте правило Asset Modules в `webpack.config.js`:
|
||||
|
||||
```js
|
||||
export default {
|
||||
module: {
|
||||
rules: [
|
||||
{
|
||||
test: /\.css$/,
|
||||
resourceQuery: /inline/,
|
||||
type: 'asset/source',
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Создайте `assets/app-icons/index.js`:
|
||||
|
||||
```js
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Зарегистрируйте generated plugin до запуска Alpine:
|
||||
|
||||
```js
|
||||
import Alpine from 'alpinejs'
|
||||
import { appAlpinePlugin } from '../assets/app-icons/index.js'
|
||||
|
||||
Alpine.plugin(appAlpinePlugin)
|
||||
Alpine.start()
|
||||
```
|
||||
|
||||
Используйте реактивную директиву на SVG-элементе:
|
||||
|
||||
```html
|
||||
<svg
|
||||
x-data="{ iconName: 'icon-name' }"
|
||||
x-app-icon="iconName"
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style="width:24px;height:24px;color:#334155;--icon-color-2:#f59e0b"
|
||||
></svg>
|
||||
```
|
||||
|
||||
Выражение директивы возвращает имя исходного SVG без расширения. Монохромная иконка наследует `color`, а слои многоцветной иконки переопределяются через `--icon-color-N`. Webpack 5 выпускает `sprite.svg` отдельным production asset.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице и нужен только при разработке. Установите его отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Добавьте Viewer в development entry:
|
||||
|
||||
```js
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
import spriteManifest from '../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'
|
||||
|
||||
const viewer = document.createElement('gromlab-sprite-viewer')
|
||||
viewer.viewerTitle = 'Иконки проекта'
|
||||
viewer.sources = [spriteManifest]
|
||||
document.body.append(viewer)
|
||||
```
|
||||
|
||||
Подключайте этот entry только при разработке. Viewer не зависит от Alpine plugin.
|
||||
@@ -0,0 +1,94 @@
|
||||
# SVG-спрайт для Angular с Application Builder
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в Angular-приложении на `@angular/build:application`.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "angular@application",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта. Запускайте генерацию через `npx` перед разработкой и production-сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"prestart": "npm run sprites",
|
||||
"start": "ng serve",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "ng build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Application Builder выпускает импортированный SVG отдельным файлом при включённом file loader. Добавьте опцию в build target файла `angular.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"builder": "@angular/build:application",
|
||||
"options": {
|
||||
"loader": { ".svg": "file" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Создайте `assets/app-icons/index.ts`:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite/index'
|
||||
```
|
||||
|
||||
Импортируйте сгенерированный standalone-компонент. Значение `name: "app"` создаёт `AppIcon` с селектором `app-icon`:
|
||||
|
||||
```ts
|
||||
import { Component } from '@angular/core'
|
||||
import { AppIcon } from '../assets/app-icons'
|
||||
|
||||
@Component({
|
||||
selector: 'app-root',
|
||||
standalone: true,
|
||||
imports: [AppIcon],
|
||||
template: `
|
||||
<app-icon
|
||||
icon="icon-name"
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style="width: 24px; height: 24px; color: #334155; --icon-color-2: #f59e0b"
|
||||
/>
|
||||
`,
|
||||
})
|
||||
export class AppComponent {}
|
||||
```
|
||||
|
||||
Input `icon` типизирован именами исходных файлов. Монохромные иконки наследуют `color`, отдельные цвета задаются через `--icon-color-N`.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer необязателен и нужен только при разработке:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Импортируйте `@gromlab/svg-sprites/viewer/element`, добавьте `CUSTOM_ELEMENTS_SCHEMA` и поместите `<gromlab-sprite-viewer [sources]="viewerSources" />` в шаблон. Загрузите generated manifest без framework-specific metadata:
|
||||
|
||||
```ts
|
||||
readonly viewerSources = [async () => {
|
||||
const { default: manifest } = await import(
|
||||
'../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'
|
||||
)
|
||||
const { usage: _usage, ...viewerManifest } = manifest
|
||||
return viewerManifest
|
||||
}]
|
||||
```
|
||||
|
||||
Viewer использует тот же production URL спрайта, что и `AppIcon`.
|
||||
@@ -0,0 +1,93 @@
|
||||
# SVG-спрайт для Angular на Webpack
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в Angular-приложении со штатным Webpack browser builder из Angular CLI.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "angular@webpack",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Mode предназначен для workspace, где build target использует официальный Webpack builder:
|
||||
|
||||
```json
|
||||
{
|
||||
"builder": "@angular-devkit/build-angular:browser"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта. Генерируйте спрайт через `npx` перед каждым запуском и сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"prestart": "npm run sprites",
|
||||
"start": "ng serve",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "ng build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Webpack разрешает generated-выражение `new URL(..., import.meta.url)` и выпускает `sprite.svg` как production asset.
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Создайте `assets/app-icons/index.ts`:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite/index'
|
||||
```
|
||||
|
||||
Импортируйте сгенерированный standalone-компонент. Значение `name: "app"` создаёт `AppIcon` с селектором `app-icon`:
|
||||
|
||||
```ts
|
||||
import { Component } from '@angular/core'
|
||||
import { AppIcon } from '../assets/app-icons'
|
||||
|
||||
@Component({
|
||||
selector: 'app-root',
|
||||
standalone: true,
|
||||
imports: [AppIcon],
|
||||
template: `
|
||||
<app-icon
|
||||
icon="icon-name"
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style="width: 24px; height: 24px; color: #334155; --icon-color-2: #f59e0b"
|
||||
/>
|
||||
`,
|
||||
})
|
||||
export class AppComponent {}
|
||||
```
|
||||
|
||||
Input `icon` типизирован именами исходных файлов. Монохромные иконки наследуют `color`, отдельные цвета задаются через `--icon-color-N`.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer необязателен и нужен только при разработке:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Импортируйте `@gromlab/svg-sprites/viewer/element`, добавьте `CUSTOM_ELEMENTS_SCHEMA` и поместите `<gromlab-sprite-viewer [sources]="viewerSources" />` в шаблон:
|
||||
|
||||
```ts
|
||||
readonly viewerSources = [async () => {
|
||||
const { default: manifest } = await import(
|
||||
'../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'
|
||||
)
|
||||
const { usage: _usage, ...viewerManifest } = manifest
|
||||
return viewerManifest
|
||||
}]
|
||||
```
|
||||
|
||||
Viewer и `AppIcon` используют один выпущенный Webpack URL спрайта.
|
||||
@@ -0,0 +1,92 @@
|
||||
# SVG-спрайт для Astro на Vite
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в Astro-приложении на Vite.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "astro@vite",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта. Генерируйте спрайт через `npx` перед разработкой и production-сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "astro dev",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "astro check && astro build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Создайте `assets/app-icons/index.js`:
|
||||
|
||||
```js
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Создайте `assets/app-icons/index.d.ts` для того же типизированного API:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Значение `name: "app"` создаёт нативный Astro-компонент `AppIcon`. Используйте его на странице:
|
||||
|
||||
```astro
|
||||
---
|
||||
import { AppIcon } from '../../assets/app-icons/index.js'
|
||||
---
|
||||
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width="24"
|
||||
height="24"
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style="color: #334155; --icon-color-2: #f59e0b"
|
||||
/>
|
||||
```
|
||||
|
||||
Prop `icon` типизирован именами исходных файлов. Vite выпускает `sprite.svg` из статического asset import компонента.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer необязателен и нужен только при разработке:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Добавьте Viewer на страницу и подключите generated manifest в клиентском скрипте:
|
||||
|
||||
```astro
|
||||
<gromlab-sprite-viewer id="sprite-viewer"></gromlab-sprite-viewer>
|
||||
|
||||
<script>
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
import type { SpriteViewerElement } from '@gromlab/svg-sprites/viewer'
|
||||
|
||||
const viewer = document.querySelector<SpriteViewerElement>('#sprite-viewer')!
|
||||
viewer.sources = [async () => {
|
||||
const { default: manifest } = await import(
|
||||
'../../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'
|
||||
)
|
||||
const { usage: _usage, ...viewerManifest } = manifest
|
||||
return viewerManifest
|
||||
}]
|
||||
</script>
|
||||
```
|
||||
|
||||
Manifest сохраняет Astro usage metadata, а Viewer отображает тот же production-спрайт.
|
||||
@@ -0,0 +1,86 @@
|
||||
# SVG-спрайт для Lit на Vite
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в Lit-приложении на Vite.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "lit@vite",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Генератор не нужно добавлять в зависимости приложения: запускайте его через `npx`.
|
||||
|
||||
Добавьте генерацию перед запуском разработки и production-сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "vite",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "vite build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт Lit-класс `AppIcon`, тег `<app-icon>` и функцию регистрации `defineAppIcon`.
|
||||
|
||||
Создайте `assets/app-icons/index.js`:
|
||||
|
||||
```js
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Зарегистрируйте компонент перед его отображением:
|
||||
|
||||
```js
|
||||
import { defineAppIcon } from '../assets/app-icons/index.js'
|
||||
|
||||
defineAppIcon()
|
||||
|
||||
document.querySelector('#app').innerHTML = `
|
||||
<app-icon
|
||||
icon="icon-name"
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style="width:24px;height:24px;color:#334155;--icon-color-2:#f59e0b"
|
||||
></app-icon>
|
||||
`
|
||||
```
|
||||
|
||||
Свойство `icon` принимает имя исходного SVG без расширения. Монохромная иконка наследует `color`, а слои многоцветной иконки переопределяются через `--icon-color-N`. Vite подключает CSS компонента и выпускает `sprite.svg` отдельным production asset.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице и нужен только при разработке. Установите его отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Добавьте Viewer на development-страницу:
|
||||
|
||||
```html
|
||||
<gromlab-sprite-viewer viewer-title="Иконки проекта"></gromlab-sprite-viewer>
|
||||
<script type="module" src="/src/svg-sprite-debug.js"></script>
|
||||
```
|
||||
|
||||
Создайте `src/svg-sprite-debug.js`:
|
||||
|
||||
```js
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
import spriteManifest from '../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'
|
||||
|
||||
document.querySelector('gromlab-sprite-viewer').sources = [spriteManifest]
|
||||
```
|
||||
|
||||
Запустите `npm run dev` и откройте development-страницу. Viewer не требуется для работы `AppIcon`.
|
||||
@@ -0,0 +1,98 @@
|
||||
# SVG-спрайт для Lit на Webpack 5
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в Lit-приложении на Webpack 5.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "lit@webpack",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Генератор не нужно добавлять в зависимости приложения: запускайте его через `npx`.
|
||||
|
||||
Добавьте генерацию перед запуском разработки и production-сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "webpack serve --mode development",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "webpack --mode production"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт Lit-класс `AppIcon`, тег `<app-icon>` и функцию регистрации `defineAppIcon`.
|
||||
|
||||
Generated CSS Lit импортируется с query `?inline`. Добавьте правило Asset Modules в `webpack.config.js`:
|
||||
|
||||
```js
|
||||
export default {
|
||||
module: {
|
||||
rules: [
|
||||
{
|
||||
test: /\.css$/,
|
||||
resourceQuery: /inline/,
|
||||
type: 'asset/source',
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Создайте `assets/app-icons/index.js`:
|
||||
|
||||
```js
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Зарегистрируйте компонент перед его отображением:
|
||||
|
||||
```js
|
||||
import { defineAppIcon } from '../assets/app-icons/index.js'
|
||||
|
||||
defineAppIcon()
|
||||
|
||||
document.querySelector('#app').innerHTML = `
|
||||
<app-icon
|
||||
icon="icon-name"
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style="width:24px;height:24px;color:#334155;--icon-color-2:#f59e0b"
|
||||
></app-icon>
|
||||
`
|
||||
```
|
||||
|
||||
Свойство `icon` принимает имя исходного SVG без расширения. Монохромная иконка наследует `color`, а слои многоцветной иконки переопределяются через `--icon-color-N`. Webpack 5 выпускает `sprite.svg` отдельным production asset.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице и нужен только при разработке. Установите его отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Добавьте Viewer в development entry:
|
||||
|
||||
```js
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
import spriteManifest from '../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'
|
||||
|
||||
const viewer = document.createElement('gromlab-sprite-viewer')
|
||||
viewer.viewerTitle = 'Иконки проекта'
|
||||
viewer.sources = [spriteManifest]
|
||||
document.body.append(viewer)
|
||||
```
|
||||
|
||||
Подключайте этот entry только при разработке. Viewer не требуется для работы `AppIcon`.
|
||||
@@ -0,0 +1,108 @@
|
||||
# SVG-спрайт для Next.js App Router с Turbopack
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в приложении Next.js с App Router и Turbopack.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
Пример конфига:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "next@app/turbopack",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта: генерация запускается через `npx`.
|
||||
|
||||
Добавьте команды генерации в `package.json`. Сгенерированные файлы по умолчанию исключены из Git, поэтому `predev` и `prebuild` пересобирают спрайт перед каждым запуском и сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "next dev --turbopack",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "next build --turbopack"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт React-компонент `AppIcon`.
|
||||
|
||||
Создайте точку входа `assets/app-icons/index.ts`:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Используйте компонент в Server Component:
|
||||
|
||||
```tsx
|
||||
// app/page.tsx
|
||||
import { AppIcon } from '../assets/app-icons'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width={24}
|
||||
height={24}
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style={{
|
||||
color: '#334155',
|
||||
'--icon-color-2': '#f59e0b',
|
||||
}}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Для `AppIcon` не нужен `'use client'`. Turbopack сам добавляет `sprite.svg` в итоговую сборку, поэтому переносить его в `public` не нужно.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице, позволяет проверить их отображение, изменить цвета и посмотреть связанные CSS-переменные. Он нужен только для разработки и устанавливается отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Создайте Client Component `app/svg-sprite/SvgSpriteViewer.tsx`:
|
||||
|
||||
```tsx
|
||||
'use client'
|
||||
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('../../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
|
||||
] as const
|
||||
|
||||
export function SvgSpriteViewer() {
|
||||
return <SpriteViewer sources={sources} title="Иконки проекта" />
|
||||
}
|
||||
```
|
||||
|
||||
Создайте маршрут `app/svg-sprite/page.tsx`:
|
||||
|
||||
```tsx
|
||||
import { notFound } from 'next/navigation'
|
||||
|
||||
import { SvgSpriteViewer } from './SvgSpriteViewer'
|
||||
|
||||
export default function SvgSpritePage() {
|
||||
if (process.env.NODE_ENV !== 'development') notFound()
|
||||
|
||||
return <SvgSpriteViewer />
|
||||
}
|
||||
```
|
||||
|
||||
Запустите `npm run dev` и откройте `/svg-sprite`. В production маршрут вернёт 404.
|
||||
@@ -0,0 +1,108 @@
|
||||
# SVG-спрайт для Next.js App Router с Webpack
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в приложении Next.js с App Router и Webpack.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
Пример конфига:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "next@app/webpack",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта: генерация запускается через `npx`.
|
||||
|
||||
Добавьте команды генерации в `package.json`. Сгенерированные файлы по умолчанию исключены из Git, поэтому `predev` и `prebuild` пересобирают спрайт перед каждым запуском и сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "next dev --webpack",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "next build --webpack"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт React-компонент `AppIcon`.
|
||||
|
||||
Создайте точку входа `assets/app-icons/index.ts`:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Используйте компонент в Server Component:
|
||||
|
||||
```tsx
|
||||
// app/page.tsx
|
||||
import { AppIcon } from '../assets/app-icons'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width={24}
|
||||
height={24}
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style={{
|
||||
color: '#334155',
|
||||
'--icon-color-2': '#f59e0b',
|
||||
}}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Для `AppIcon` не нужен `'use client'`. Next.js сам добавляет `sprite.svg` в итоговую сборку, поэтому переносить его в `public` не нужно.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице, позволяет проверить их отображение, изменить цвета и посмотреть связанные CSS-переменные. Он нужен только для разработки и устанавливается отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Создайте Client Component `app/svg-sprite/SvgSpriteViewer.tsx`:
|
||||
|
||||
```tsx
|
||||
'use client'
|
||||
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('../../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
|
||||
] as const
|
||||
|
||||
export function SvgSpriteViewer() {
|
||||
return <SpriteViewer sources={sources} title="Иконки проекта" />
|
||||
}
|
||||
```
|
||||
|
||||
Создайте маршрут `app/svg-sprite/page.tsx`:
|
||||
|
||||
```tsx
|
||||
import { notFound } from 'next/navigation'
|
||||
|
||||
import { SvgSpriteViewer } from './SvgSpriteViewer'
|
||||
|
||||
export default function SvgSpritePage() {
|
||||
if (process.env.NODE_ENV !== 'development') notFound()
|
||||
|
||||
return <SvgSpriteViewer />
|
||||
}
|
||||
```
|
||||
|
||||
Запустите `npm run dev` и откройте `/svg-sprite`. В production маршрут вернёт 404.
|
||||
@@ -0,0 +1,98 @@
|
||||
# SVG-спрайт для Next.js Pages Router с Turbopack
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в приложении Next.js с Pages Router и Turbopack.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
Пример конфига:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "next@pages/turbopack",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта: генерация запускается через `npx`.
|
||||
|
||||
Добавьте команды генерации в `package.json`. Сгенерированные файлы по умолчанию исключены из Git, поэтому `predev` и `prebuild` пересобирают спрайт перед каждым запуском и сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "next dev --turbopack",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "next build --turbopack"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт React-компонент `AppIcon`.
|
||||
|
||||
Создайте точку входа `assets/app-icons/index.ts`:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Используйте компонент на странице:
|
||||
|
||||
```tsx
|
||||
// pages/index.tsx
|
||||
import { AppIcon } from '../assets/app-icons'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width={24}
|
||||
height={24}
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style={{
|
||||
color: '#334155',
|
||||
'--icon-color-2': '#f59e0b',
|
||||
}}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Компонент работает с SSR, SSG и клиентскими переходами. Turbopack сам добавляет `sprite.svg` в итоговую сборку, поэтому переносить его в `public` не нужно.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице, позволяет проверить их отображение, изменить цвета и посмотреть связанные CSS-переменные. Он нужен только для разработки и устанавливается отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Создайте страницу `pages/svg-sprite.tsx`:
|
||||
|
||||
```tsx
|
||||
import type { GetStaticProps } from 'next'
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
|
||||
] as const
|
||||
|
||||
export default function SvgSpritePage() {
|
||||
return <SpriteViewer sources={sources} title="Иконки проекта" />
|
||||
}
|
||||
|
||||
export const getStaticProps: GetStaticProps = () =>
|
||||
process.env.NODE_ENV === 'development'
|
||||
? { props: {} }
|
||||
: { notFound: true }
|
||||
```
|
||||
|
||||
Запустите `npm run dev` и откройте `/svg-sprite`. В production маршрут вернёт 404.
|
||||
@@ -0,0 +1,98 @@
|
||||
# SVG-спрайт для Next.js Pages Router с Webpack
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в приложении Next.js с Pages Router и Webpack.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
Пример конфига:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "next@pages/webpack",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта: генерация запускается через `npx`.
|
||||
|
||||
Добавьте команды генерации в `package.json`. Сгенерированные файлы по умолчанию исключены из Git, поэтому `predev` и `prebuild` пересобирают спрайт перед каждым запуском и сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "next dev --webpack",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "next build --webpack"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт React-компонент `AppIcon`.
|
||||
|
||||
Создайте точку входа `assets/app-icons/index.ts`:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Используйте компонент на странице:
|
||||
|
||||
```tsx
|
||||
// pages/index.tsx
|
||||
import { AppIcon } from '../assets/app-icons'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width={24}
|
||||
height={24}
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style={{
|
||||
color: '#334155',
|
||||
'--icon-color-2': '#f59e0b',
|
||||
}}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Компонент работает с SSR, SSG и клиентскими переходами. Next.js сам добавляет `sprite.svg` в итоговую сборку, поэтому переносить его в `public` не нужно.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице, позволяет проверить их отображение, изменить цвета и посмотреть связанные CSS-переменные. Он нужен только для разработки и устанавливается отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Создайте страницу `pages/svg-sprite.tsx`:
|
||||
|
||||
```tsx
|
||||
import type { GetStaticProps } from 'next'
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
|
||||
] as const
|
||||
|
||||
export default function SvgSpritePage() {
|
||||
return <SpriteViewer sources={sources} title="Иконки проекта" />
|
||||
}
|
||||
|
||||
export const getStaticProps: GetStaticProps = () =>
|
||||
process.env.NODE_ENV === 'development'
|
||||
? { props: {} }
|
||||
: { notFound: true }
|
||||
```
|
||||
|
||||
Запустите `npm run dev` и откройте `/svg-sprite`. В production маршрут вернёт 404.
|
||||
@@ -0,0 +1,100 @@
|
||||
# SVG-спрайт для Nuxt на Vite
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в Nuxt-приложении на Vite.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
Пример конфига:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "nuxt@vite",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта: генерация запускается через `npx`.
|
||||
|
||||
Добавьте команды генерации в `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "nuxt dev",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "nuxt build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт Vue-компонент `AppIcon`. Создайте `assets/app-icons/index.js`:
|
||||
|
||||
```js
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Используйте компонент на странице или в layout Nuxt:
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import { AppIcon } from '../assets/app-icons/index.js'
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width="24"
|
||||
height="24"
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style="color: #334155; --icon-color-2: #f59e0b"
|
||||
/>
|
||||
</template>
|
||||
```
|
||||
|
||||
`AppIcon` безопасен для SSR и не требует client-only обёртки. Vite выпускает `sprite.svg` отдельным production asset.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице, позволяет проверить их отображение, изменить цвета и посмотреть связанные CSS-переменные. Он нужен только для разработки и устанавливается отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Создайте `app/components/SvgSpriteViewer.client.vue`, чтобы browser-only Viewer не выполнялся во время SSR:
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
|
||||
const sources = [
|
||||
() => import('../../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
|
||||
]
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<gromlab-sprite-viewer :sources="sources" viewer-title="Иконки проекта" />
|
||||
</template>
|
||||
```
|
||||
|
||||
Отметьте `gromlab-sprite-viewer` как custom element в `nuxt.config.ts`:
|
||||
|
||||
```ts
|
||||
export default defineNuxtConfig({
|
||||
vue: {
|
||||
compilerOptions: {
|
||||
isCustomElement: (tag) => tag === 'gromlab-sprite-viewer',
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
Покажите `<SvgSpriteViewer />` на странице разработки. Viewer изолирован от generated runtime компонента `AppIcon`.
|
||||
@@ -0,0 +1,113 @@
|
||||
# SVG-спрайт для Nuxt на Webpack
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в Nuxt-приложении на Webpack.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
Пример конфига:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "nuxt@webpack",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта: генерация запускается через `npx`.
|
||||
|
||||
Подключите Webpack builder Nuxt в `nuxt.config.ts`:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @nuxt/webpack-builder
|
||||
```
|
||||
|
||||
```ts
|
||||
export default defineNuxtConfig({
|
||||
builder: '@nuxt/webpack-builder',
|
||||
})
|
||||
```
|
||||
|
||||
Добавьте команды генерации в `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "nuxt dev",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "nuxt build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт Vue-компонент `AppIcon`. Создайте `assets/app-icons/index.js`:
|
||||
|
||||
```js
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Используйте компонент на странице или в layout Nuxt:
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import { AppIcon } from '../assets/app-icons/index.js'
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width="24"
|
||||
height="24"
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style="color: #334155; --icon-color-2: #f59e0b"
|
||||
/>
|
||||
</template>
|
||||
```
|
||||
|
||||
`AppIcon` безопасен для SSR и не требует client-only обёртки. Webpack выпускает `sprite.svg` отдельным production asset.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице, позволяет проверить их отображение, изменить цвета и посмотреть связанные CSS-переменные. Он нужен только для разработки и устанавливается отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Создайте `app/components/SvgSpriteViewer.client.vue`, чтобы browser-only Viewer не выполнялся во время SSR:
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
|
||||
const sources = [
|
||||
() => import('../../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
|
||||
]
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<gromlab-sprite-viewer :sources="sources" viewer-title="Иконки проекта" />
|
||||
</template>
|
||||
```
|
||||
|
||||
Дополните существующие настройки `nuxt.config.ts`, чтобы Vue считал Viewer custom element:
|
||||
|
||||
```ts
|
||||
export default defineNuxtConfig({
|
||||
builder: '@nuxt/webpack-builder',
|
||||
vue: {
|
||||
compilerOptions: {
|
||||
isCustomElement: (tag) => tag === 'gromlab-sprite-viewer',
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
Покажите `<SvgSpriteViewer />` на странице разработки. Viewer изолирован от generated runtime компонента `AppIcon`.
|
||||
@@ -0,0 +1,75 @@
|
||||
# SVG-спрайт для Preact на Vite
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в Preact-приложении на Vite.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "preact@vite",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта. Запускайте его через `npx` перед разработкой и production-сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "vite",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "tsc --noEmit && vite build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Создайте `assets/app-icons/index.js` и `assets/app-icons/index.d.ts` с одинаковым экспортом:
|
||||
|
||||
```js
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Используйте сгенерированный Preact-компонент на plain JavaScript:
|
||||
|
||||
```jsx
|
||||
import { AppIcon } from '../assets/app-icons/index.js'
|
||||
|
||||
export function SaveIcon() {
|
||||
return (
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width={24}
|
||||
height={24}
|
||||
aria-label="Готово"
|
||||
style={{ color: '#334155', '--icon-color-2': '#f59e0b' }}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Vite автоматически выпускает импортированный `sprite.svg` как production asset.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Установите Viewer только для разработки:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Подключите его в отладочной entry:
|
||||
|
||||
```js
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
|
||||
const viewer = document.createElement('gromlab-sprite-viewer')
|
||||
viewer.sources = [() => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js')]
|
||||
document.body.append(viewer)
|
||||
```
|
||||
@@ -0,0 +1,75 @@
|
||||
# SVG-спрайт для Preact на Webpack
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в Preact-приложении на Webpack 5.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "preact@webpack",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта. Запускайте его через `npx` перед запуском и сборкой Webpack:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "webpack serve --mode development",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "tsc --noEmit && webpack --mode production"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Создайте `assets/app-icons/index.js` и `assets/app-icons/index.d.ts` с одинаковым экспортом:
|
||||
|
||||
```js
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Используйте сгенерированный Preact-компонент:
|
||||
|
||||
```jsx
|
||||
import { AppIcon } from '../assets/app-icons/index.js'
|
||||
|
||||
export function SaveIcon() {
|
||||
return (
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width={24}
|
||||
height={24}
|
||||
aria-label="Готово"
|
||||
style={{ color: '#334155', '--icon-color-2': '#f59e0b' }}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Webpack Asset Modules выпускают `sprite.svg` из сгенерированного выражения `new URL(...)`.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Установите Viewer только для разработки:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Подключите его в отдельной development entry:
|
||||
|
||||
```js
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
|
||||
const viewer = document.createElement('gromlab-sprite-viewer')
|
||||
viewer.sources = [() => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js')]
|
||||
document.body.append(viewer)
|
||||
```
|
||||
@@ -0,0 +1,82 @@
|
||||
# SVG-спрайт для Qwik на Vite
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в SSR-приложении Qwik на Vite.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "qwik@vite",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта. Перегенерируйте спрайт через `npx` перед запуском и сборкой Vite:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "vite --mode ssr",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "tsc --noEmit && vite build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Создайте `assets/app-icons/index.ts`:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Сгенерированный компонент является Qwik `component$` и безопасен во время SSR:
|
||||
|
||||
```tsx
|
||||
import { component$ } from '@builder.io/qwik'
|
||||
import { AppIcon } from '../assets/app-icons'
|
||||
|
||||
export default component$(() => (
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width={24}
|
||||
height={24}
|
||||
aria-label="Готово"
|
||||
style={{ color: '#334155', '--icon-color-2': '#f59e0b' }}
|
||||
/>
|
||||
))
|
||||
```
|
||||
|
||||
Компонент использует статический Vite asset import и не обращается к browser globals во время SSR.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer работает только в браузере и нужен лишь для разработки:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Загрузите его из visible task:
|
||||
|
||||
```tsx
|
||||
import { component$, useSignal, useVisibleTask$ } from '@builder.io/qwik'
|
||||
import type { SpriteViewerElement } from '@gromlab/svg-sprites/viewer'
|
||||
|
||||
export const IconViewer = component$(() => {
|
||||
const host = useSignal<HTMLElement>()
|
||||
useVisibleTask$(async () => {
|
||||
await import('@gromlab/svg-sprites/viewer/element')
|
||||
const viewer = document.createElement('gromlab-sprite-viewer') as SpriteViewerElement
|
||||
viewer.sources = [() => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js')]
|
||||
host.value?.append(viewer)
|
||||
})
|
||||
return <div ref={host} />
|
||||
})
|
||||
```
|
||||
@@ -0,0 +1,115 @@
|
||||
# SVG-спрайт для React на Vite
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в React-приложении на Vite.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
Пример конфига:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "react@vite",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта: генерация запускается через `npx`.
|
||||
|
||||
Добавьте команды генерации в `package.json`. Сгенерированные файлы по умолчанию исключены из Git, поэтому `predev` и `prebuild` пересобирают спрайт перед каждым запуском и сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "vite",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "tsc --noEmit && vite build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт React-компонент `AppIcon`.
|
||||
|
||||
Создайте точку входа `assets/app-icons/index.ts`:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Используйте компонент в приложении:
|
||||
|
||||
```tsx
|
||||
import { AppIcon } from '../assets/app-icons'
|
||||
|
||||
export function SaveIcon() {
|
||||
return (
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width={24}
|
||||
height={24}
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style={{
|
||||
color: '#334155',
|
||||
'--icon-color-2': '#f59e0b',
|
||||
}}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Свойство `icon` принимает имена исходных SVG без расширения. Монохромная иконка наследует `color`, а цвета многоцветной переопределяются через `--icon-color-N`.
|
||||
|
||||
Vite сам подключает стили компонента и добавляет `sprite.svg` в итоговую сборку.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице, позволяет проверить их отображение, изменить цвета и посмотреть связанные CSS-переменные. Он нужен только для разработки и устанавливается отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Создайте `svg-sprite.html` в корне проекта:
|
||||
|
||||
```html
|
||||
<!doctype html>
|
||||
<html lang="ru">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Иконки проекта</title>
|
||||
</head>
|
||||
<body>
|
||||
<!-- React-корень Viewer для дебага и превью SVG-спрайта -->
|
||||
<div id="svg-sprite-viewer"></div>
|
||||
|
||||
<!-- Подключение создаваемого ниже скрипта дебаггера -->
|
||||
<script type="module" src="/src/svg-sprite-debug.tsx"></script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
Создайте `src/svg-sprite-debug.tsx`:
|
||||
|
||||
```tsx
|
||||
import { createRoot } from 'react-dom/client'
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
|
||||
] as const
|
||||
|
||||
createRoot(document.getElementById('svg-sprite-viewer')!).render(
|
||||
<SpriteViewer sources={sources} title="Иконки проекта" />,
|
||||
)
|
||||
```
|
||||
|
||||
Запустите `npm run dev` и откройте `/svg-sprite.html`.
|
||||
|
||||
Стандартная production-сборка Vite использует только `index.html` и не включает страницу Viewer.
|
||||
@@ -0,0 +1,132 @@
|
||||
# SVG-спрайт для React на Webpack 5
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в React-приложении на Webpack 5.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
Пример конфига:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "react@webpack",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта: генерация запускается через `npx`.
|
||||
|
||||
Добавьте команды генерации в `package.json`. Сгенерированные файлы по умолчанию исключены из Git, поэтому `predev` и `prebuild` пересобирают спрайт перед каждым запуском и сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "webpack serve --mode development",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "webpack --mode production"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт React-компонент `AppIcon`.
|
||||
|
||||
Создайте точку входа `assets/app-icons/index.ts`:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Используйте компонент в приложении:
|
||||
|
||||
```tsx
|
||||
import { AppIcon } from '../assets/app-icons'
|
||||
|
||||
export function SaveIcon() {
|
||||
return (
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width={24}
|
||||
height={24}
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style={{
|
||||
color: '#334155',
|
||||
'--icon-color-2': '#f59e0b',
|
||||
}}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Свойство `icon` принимает имена исходных SVG без расширения. Монохромная иконка наследует `color`, а цвета многоцветной переопределяются через `--icon-color-N`.
|
||||
|
||||
Компонент использует CSS Modules. Если проект ещё не обрабатывает их, установите loaders:
|
||||
|
||||
```bash
|
||||
npm install --save-dev style-loader css-loader
|
||||
```
|
||||
|
||||
Затем добавьте правило с default export в `webpack.config.js`:
|
||||
|
||||
```js
|
||||
{
|
||||
test: /\.module\.css$/i,
|
||||
use: [
|
||||
'style-loader',
|
||||
{
|
||||
loader: 'css-loader',
|
||||
options: { modules: { namedExport: false } },
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
Webpack 5 сам добавляет `sprite.svg` в итоговую сборку.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице, позволяет проверить их отображение, изменить цвета и посмотреть связанные CSS-переменные. Он нужен только для разработки.
|
||||
|
||||
Установите Viewer:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Создайте entry `src/svg-sprite-debug.tsx`:
|
||||
|
||||
```tsx
|
||||
import { createRoot } from 'react-dom/client'
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
|
||||
] as const
|
||||
|
||||
const container = document.createElement('div')
|
||||
document.body.append(container)
|
||||
|
||||
createRoot(container).render(
|
||||
<SpriteViewer sources={sources} title="Иконки проекта" />,
|
||||
)
|
||||
```
|
||||
|
||||
Добавьте скрипт к основному entry только в development-режиме. Сохраните остальные настройки `webpack.config.js`:
|
||||
|
||||
```js
|
||||
export default (_env, argv) => ({
|
||||
// Остальные настройки Webpack.
|
||||
entry: [
|
||||
'./src/main.tsx',
|
||||
...(argv.mode === 'development' ? ['./src/svg-sprite-debug.tsx'] : []),
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
Запустите `npm run dev`. Viewer появится на основной странице приложения и не попадёт в production-сборку.
|
||||
@@ -0,0 +1,83 @@
|
||||
# SVG-спрайт для SolidStart на Vite
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в SSR-приложении SolidStart на Vite.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "solid-start@vite",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта. Перегенерируйте спрайт через `npx` перед запуском и сборкой Vinxi:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "vinxi dev",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "vinxi build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Создайте `assets/app-icons/index.ts`:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Сгенерированный компонент безопасно рендерится на сервере:
|
||||
|
||||
```tsx
|
||||
import { AppIcon } from '../assets/app-icons'
|
||||
|
||||
export default function Home() {
|
||||
return (
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width={24}
|
||||
height={24}
|
||||
aria-label="Готово"
|
||||
style={{ color: '#334155', '--icon-color-2': '#f59e0b' }}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Компонент использует статический Vite asset import и не обращается к browser globals во время SSR.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer работает только в браузере и нужен лишь для разработки:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Загрузите его из `onMount`, чтобы исключить из серверного рендера:
|
||||
|
||||
```tsx
|
||||
import { onMount } from 'solid-js'
|
||||
import type { SpriteViewerElement } from '@gromlab/svg-sprites/viewer'
|
||||
|
||||
export function IconViewer() {
|
||||
let host!: HTMLDivElement
|
||||
onMount(async () => {
|
||||
await import('@gromlab/svg-sprites/viewer/element')
|
||||
const viewer = document.createElement('gromlab-sprite-viewer') as SpriteViewerElement
|
||||
viewer.sources = [() => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js')]
|
||||
host.append(viewer)
|
||||
})
|
||||
return <div ref={host} />
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,83 @@
|
||||
# SVG-спрайт для Solid на Vite
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в Solid-приложении на Vite.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "solid@vite",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта. Запускайте его через `npx` перед разработкой и production-сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "vite",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "tsc --noEmit && vite build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Создайте `assets/app-icons/index.ts`:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Имя `app` создаёт Solid-компонент `AppIcon`:
|
||||
|
||||
```tsx
|
||||
import { AppIcon } from '../assets/app-icons'
|
||||
|
||||
export function SaveIcon() {
|
||||
return (
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width={24}
|
||||
height={24}
|
||||
aria-label="Готово"
|
||||
style={{ color: '#334155', '--icon-color-2': '#f59e0b' }}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Vite выпускает `sprite.svg` как production asset. Монохромные иконки наследуют `color`, многоцветные используют `--icon-color-N`.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer нужен только во время разработки и устанавливается отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Подключите его в отладочном компоненте после запуска браузерного кода:
|
||||
|
||||
```tsx
|
||||
import { onMount } from 'solid-js'
|
||||
import type { SpriteViewerElement } from '@gromlab/svg-sprites/viewer'
|
||||
|
||||
export function IconViewer() {
|
||||
let host!: HTMLDivElement
|
||||
onMount(async () => {
|
||||
await import('@gromlab/svg-sprites/viewer/element')
|
||||
const viewer = document.createElement('gromlab-sprite-viewer') as SpriteViewerElement
|
||||
viewer.sources = [() => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js')]
|
||||
host.append(viewer)
|
||||
})
|
||||
return <div ref={host} />
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,75 @@
|
||||
# SVG-спрайт для Solid на Webpack
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в Solid-приложении на Webpack 5.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "solid@webpack",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта. Запускайте его через `npx` перед запуском и сборкой Webpack:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "webpack serve --mode development",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "tsc --noEmit && webpack --mode production"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Создайте `assets/app-icons/index.js` и `assets/app-icons/index.d.ts` с одинаковым экспортом:
|
||||
|
||||
```js
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Используйте сгенерированный Solid-компонент:
|
||||
|
||||
```jsx
|
||||
import { AppIcon } from '../assets/app-icons/index.js'
|
||||
|
||||
export function SaveIcon() {
|
||||
return (
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width={24}
|
||||
height={24}
|
||||
aria-label="Готово"
|
||||
style={{ color: '#334155', '--icon-color-2': '#f59e0b' }}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Webpack Asset Modules выпускают `sprite.svg` из сгенерированного `new URL(...)`. Обработка `.jsx` должна охватывать сгенерированный Solid-компонент.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Установите Viewer только для разработки:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Подключите его в отдельной development entry:
|
||||
|
||||
```js
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
|
||||
const viewer = document.createElement('gromlab-sprite-viewer')
|
||||
viewer.sources = [() => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js')]
|
||||
document.body.append(viewer)
|
||||
```
|
||||
@@ -0,0 +1,113 @@
|
||||
# Универсальный SVG-спрайт на сервере
|
||||
|
||||
Сгенерируйте в CI или server worker универсальный SVG-спрайт, который смогут использовать приложения с разными frameworks и bundlers.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Устанавливать пакет в worker не нужно.
|
||||
|
||||
### 1. Подготовьте рабочий каталог
|
||||
|
||||
Поместите исходные SVG в папку `icons` текущего workspace:
|
||||
|
||||
```text
|
||||
.
|
||||
└── icons/
|
||||
├── search.svg
|
||||
└── settings.svg
|
||||
```
|
||||
|
||||
Имена файлов без расширения станут именами иконок.
|
||||
|
||||
### 2. Запустите генерацию
|
||||
|
||||
Передайте mode, имя спрайта и путь к SVG через CLI:
|
||||
|
||||
```bash
|
||||
npx --yes @gromlab/svg-sprites \
|
||||
--mode standalone@server \
|
||||
--name app \
|
||||
--input './icons/**/*.svg' \
|
||||
.
|
||||
```
|
||||
|
||||
Config-файл для этого worker-сценария не нужен. Результат появится в `./.svg-sprite`:
|
||||
|
||||
```text
|
||||
.
|
||||
├── icons/
|
||||
│ ├── search.svg
|
||||
│ └── settings.svg
|
||||
└── .svg-sprite/
|
||||
├── sprite.<content-hash>.svg
|
||||
├── sprite-root-viewbox.<content-hash>.svg
|
||||
└── svg-sprite.manifest.json
|
||||
```
|
||||
|
||||
### 3. Опубликуйте результат
|
||||
|
||||
Загрузите содержимое `.svg-sprite` в отдельный каталог S3 bucket:
|
||||
|
||||
```bash
|
||||
aws s3 sync ./.svg-sprite/ s3://my-bucket/app-icons/
|
||||
```
|
||||
|
||||
Этот же каталог можно раздавать через CDN. В публичном URL нет сегмента `.svg-sprite`:
|
||||
|
||||
```text
|
||||
https://cdn.example.com/app-icons/
|
||||
├── sprite.<content-hash>.svg
|
||||
├── sprite-root-viewbox.<content-hash>.svg
|
||||
└── svg-sprite.manifest.json
|
||||
```
|
||||
|
||||
`standalone@server` также можно запускать через JSON, JavaScript или TypeScript config. Config подходит для постоянных настроек, локальных SVG из нескольких каталогов и SVG, загружаемых по HTTP(S).
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
В consumer-приложении создайте обычный config. Например, для React с Vite:
|
||||
|
||||
```text
|
||||
src/app-icons/
|
||||
├── index.ts
|
||||
└── svg-sprite.config.json
|
||||
```
|
||||
|
||||
Укажите consumer mode и URL manifest из CDN:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "react@vite",
|
||||
"source": "remote",
|
||||
"input": "https://cdn.example.com/app-icons/svg-sprite.manifest.json"
|
||||
}
|
||||
```
|
||||
|
||||
Добавьте пользовательскую точку входа:
|
||||
|
||||
```ts
|
||||
// src/app-icons/index.ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Запустите обычную генерацию:
|
||||
|
||||
```bash
|
||||
npx --yes @gromlab/svg-sprites src/app-icons/svg-sprite.config.json
|
||||
```
|
||||
|
||||
После этого используйте generated-компонент так же, как со спрайтом из локальных SVG:
|
||||
|
||||
```tsx
|
||||
import { AppIcon } from './app-icons'
|
||||
|
||||
export function SearchButton() {
|
||||
return <AppIcon icon="search" aria-label="Поиск" />
|
||||
}
|
||||
```
|
||||
|
||||
Тот же CDN manifest поддерживают все 29 consumer modes. В каждом из них сохраняется нативный API выбранного framework и bundler.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
`standalone@server` не создаёт отдельную страницу для просмотра иконок. Подключите опубликованный спрайт к consumer-приложению и откройте его в SpriteViewer: удалённый набор будет отображаться так же, как локальный.
|
||||
@@ -0,0 +1,114 @@
|
||||
# SVG-спрайт для Vite без фреймворка
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в приложении на Vite без фреймворка.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
Пример конфига:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "standalone@vite",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта: генерация запускается через `npx`.
|
||||
|
||||
Добавьте команды генерации в `package.json`. Сгенерированные файлы по умолчанию исключены из Git, поэтому `predev` и `prebuild` пересобирают спрайт перед каждым запуском и сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "vite",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "vite build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт элемент `<app-icon>`.
|
||||
|
||||
Создайте точку входа `assets/app-icons/index.ts`:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Зарегистрируйте элемент в `src/main.ts`:
|
||||
|
||||
```ts
|
||||
import { defineAppIconElement } from '../assets/app-icons'
|
||||
import './style.css'
|
||||
|
||||
defineAppIconElement()
|
||||
```
|
||||
|
||||
Используйте иконку в HTML:
|
||||
|
||||
```html
|
||||
<app-icon icon="icon-name" role="img" aria-label="Готово"></app-icon>
|
||||
```
|
||||
|
||||
Значение `icon` — имя исходного SVG без расширения. Размер и цвета настраиваются через CSS:
|
||||
|
||||
```css
|
||||
app-icon {
|
||||
font-size: 24px;
|
||||
color: #334155;
|
||||
--icon-color-2: #f59e0b;
|
||||
}
|
||||
```
|
||||
|
||||
Монохромная иконка наследует `color`, а цвета многоцветной иконки переопределяются через `--icon-color-N`. Нужные переменные показывает Viewer.
|
||||
|
||||
Vite сам добавит `sprite.svg` в итоговую сборку. Копировать его в `public` не нужно.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице, позволяет проверить их отображение, изменить цвета и посмотреть связанные CSS-переменные. Он нужен только для разработки и устанавливается отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Создайте `svg-sprite.html` в корне проекта:
|
||||
|
||||
```html
|
||||
<!doctype html>
|
||||
<html lang="ru">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Иконки проекта</title>
|
||||
</head>
|
||||
<body>
|
||||
<!-- Компонент Viewer для дебага и превью SVG-спрайта -->
|
||||
<gromlab-sprite-viewer viewer-title="Иконки проекта"></gromlab-sprite-viewer>
|
||||
|
||||
<!-- Подключение создаваемого ниже скрипта дебаггера -->
|
||||
<script type="module" src="/src/svg-sprite-debug.ts"></script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
Создайте `src/svg-sprite-debug.ts`:
|
||||
|
||||
```ts
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
import type { SpriteViewerElement } from '@gromlab/svg-sprites/viewer'
|
||||
import spriteManifest from '../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'
|
||||
|
||||
const viewer = document.querySelector<SpriteViewerElement>('gromlab-sprite-viewer')!
|
||||
viewer.sources = [spriteManifest]
|
||||
```
|
||||
|
||||
Запустите `npm run dev` и откройте `/svg-sprite.html`.
|
||||
|
||||
Viewer не требуется для работы `<app-icon>` и не подключается к основному коду приложения.
|
||||
@@ -0,0 +1,111 @@
|
||||
# SVG-спрайт для Webpack 5 без фреймворка
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в приложении на Webpack 5 без фреймворка.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
Пример конфига:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "standalone@webpack",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта: генерация запускается через `npx`.
|
||||
|
||||
Добавьте команды генерации в `package.json`. Сгенерированные файлы по умолчанию исключены из Git, поэтому `predev` и `prebuild` пересобирают спрайт перед каждым запуском и сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "webpack serve --mode development",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "webpack --mode production"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт элемент `<app-icon>`.
|
||||
|
||||
Создайте точку входа `assets/app-icons/index.ts`:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Зарегистрируйте элемент в основном entry приложения:
|
||||
|
||||
```ts
|
||||
import { defineAppIconElement } from '../assets/app-icons'
|
||||
import './style.css'
|
||||
|
||||
defineAppIconElement()
|
||||
```
|
||||
|
||||
Используйте иконку в HTML:
|
||||
|
||||
```html
|
||||
<app-icon icon="icon-name" role="img" aria-label="Готово"></app-icon>
|
||||
```
|
||||
|
||||
Значение `icon` — имя исходного SVG без расширения. Размер и цвета настраиваются через CSS:
|
||||
|
||||
```css
|
||||
app-icon {
|
||||
font-size: 24px;
|
||||
color: #334155;
|
||||
--icon-color-2: #f59e0b;
|
||||
}
|
||||
```
|
||||
|
||||
Монохромная иконка наследует `color`, а цвета многоцветной иконки переопределяются через `--icon-color-N`. Нужные переменные показывает Viewer.
|
||||
|
||||
Webpack 5 сам добавит `sprite.svg` в итоговую сборку.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице, позволяет проверить их отображение, изменить цвета и посмотреть связанные CSS-переменные. Он нужен только для разработки.
|
||||
|
||||
Установите Viewer:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Создайте entry `src/svg-sprite-debug.ts`:
|
||||
|
||||
```ts
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
import type { SpriteViewerElement } from '@gromlab/svg-sprites/viewer'
|
||||
import spriteManifest from '../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'
|
||||
|
||||
const viewer = document.createElement('gromlab-sprite-viewer') as SpriteViewerElement
|
||||
viewer.viewerTitle = 'Иконки проекта'
|
||||
viewer.sources = [spriteManifest]
|
||||
document.body.append(viewer)
|
||||
```
|
||||
|
||||
Добавьте скрипт к основному entry только в development-режиме. Сохраните остальные настройки `webpack.config.js`:
|
||||
|
||||
```js
|
||||
export default (_env, argv) => ({
|
||||
// Остальные настройки Webpack.
|
||||
entry: [
|
||||
'./src/main.ts',
|
||||
...(argv.mode === 'development' ? ['./src/svg-sprite-debug.ts'] : []),
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
Запустите `npm run dev`. Viewer появится на основной странице приложения.
|
||||
|
||||
Viewer добавляется только в development-сборку и не попадает в production.
|
||||
@@ -0,0 +1,83 @@
|
||||
# SVG-спрайт для сайта без сборщика
|
||||
|
||||
Соберите SVG-иконки в один файл и используйте их на HTML-странице.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Устанавливать пакет в проект не нужно.
|
||||
|
||||
### 1. Создайте конфиг спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "standalone",
|
||||
"name": "icons",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Сгенерируйте спрайт
|
||||
|
||||
Передайте команде путь к конфигу:
|
||||
|
||||
```bash
|
||||
npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json
|
||||
```
|
||||
|
||||
Пакет соберёт иконки в каталог `.svg-sprite` рядом с конфигом:
|
||||
|
||||
```text
|
||||
assets/app-icons/.svg-sprite/
|
||||
├── sprite.svg
|
||||
└── svg-sprite.manifest.json
|
||||
```
|
||||
|
||||
- `sprite.svg` — готовый спрайт для использования на сайте.
|
||||
- `svg-sprite.manifest.json` — данные об иконках для Viewer.
|
||||
|
||||
Каталог `.svg-sprite` создаётся автоматически и полностью заменяется при каждой генерации. Не редактируйте его содержимое вручную.
|
||||
|
||||
### 3. Используйте иконку
|
||||
|
||||
В `index.html` укажите путь к созданному `sprite.svg`. После `#` добавьте имя нужной иконки без расширения `.svg`:
|
||||
|
||||
```html
|
||||
<svg
|
||||
width="24"
|
||||
height="24"
|
||||
aria-label="Готово"
|
||||
>
|
||||
<use href="./assets/app-icons/.svg-sprite/sprite.svg#icon-name"></use>
|
||||
</svg>
|
||||
```
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
`sprite.svg` — технический файл, а не галерея иконок. При его открытии нельзя удобно просмотреть весь набор. Кроме того, градиенты, маски, фильтры и ссылки на внутренние `id` могут отображаться с артефактами.
|
||||
|
||||
Для визуальной проверки используйте официальный Viewer. Он показывает все иконки спрайта и помогает проверить их цвета и отображение.
|
||||
|
||||
Viewer необязателен и предназначен только для разработки. Устанавливать пакет через npm не нужно.
|
||||
|
||||
Viewer работает напрямую с файлами из `.svg-sprite`. Ничего копировать не нужно.
|
||||
|
||||
### Добавьте Viewer на страницу
|
||||
|
||||
Добавьте в `index.html` module script и укажите пути к generated manifest и спрайту:
|
||||
|
||||
```html
|
||||
<script
|
||||
type="module"
|
||||
src="https://cdn.jsdelivr.net/npm/@gromlab/svg-sprites/dist/viewer-element.js"
|
||||
></script>
|
||||
|
||||
<gromlab-sprite-viewer
|
||||
viewer-title="Иконки проекта"
|
||||
manifest-url="./assets/app-icons/.svg-sprite/svg-sprite.manifest.json"
|
||||
sprite-url="./assets/app-icons/.svg-sprite/sprite.svg"
|
||||
></gromlab-sprite-viewer>
|
||||
```
|
||||
|
||||
Viewer можно вынести в отдельный HTML-файл в корне сайта, предназначенный только для разработки и проверки иконок.
|
||||
@@ -0,0 +1,95 @@
|
||||
# SVG-спрайт для Svelte на Vite
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в Svelte-приложении на Vite.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
Пример конфига:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "svelte@vite",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта: генерация запускается через `npx`.
|
||||
|
||||
Добавьте команды генерации в `package.json`. Сгенерированные файлы по умолчанию исключены из Git, поэтому `predev` и `prebuild` пересобирают спрайт перед каждым запуском и сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "vite",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "vite build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт Svelte-компонент `AppIcon`.
|
||||
|
||||
Создайте `assets/app-icons/index.js`:
|
||||
|
||||
```js
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Используйте компонент в приложении:
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
import { AppIcon } from '../assets/app-icons/index.js'
|
||||
</script>
|
||||
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width="24"
|
||||
height="24"
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style="color: #334155; --icon-color-2: #f59e0b"
|
||||
/>
|
||||
```
|
||||
|
||||
Свойство `icon` принимает имена исходных SVG без расширения. Монохромная иконка наследует `color`, а цвета многоцветной переопределяются через `--icon-color-N`.
|
||||
|
||||
Vite сам подключает стили компонента и выпускает `sprite.svg` отдельным production asset.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице, позволяет проверить их отображение, изменить цвета и посмотреть связанные CSS-переменные. Он нужен только для разработки и устанавливается отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Добавьте Viewer на страницу или в компонент, используемый только при разработке:
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
|
||||
const sources = [
|
||||
() => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
|
||||
]
|
||||
|
||||
function connectViewer(node) {
|
||||
node.sources = sources
|
||||
}
|
||||
</script>
|
||||
|
||||
<gromlab-sprite-viewer
|
||||
use:connectViewer
|
||||
viewer-title="Иконки проекта"
|
||||
></gromlab-sprite-viewer>
|
||||
```
|
||||
|
||||
Запустите `npm run dev` и откройте страницу с Viewer. Не импортируйте этот отладочный компонент из production entry.
|
||||
@@ -0,0 +1,105 @@
|
||||
# SVG-спрайт для Svelte на Webpack 5
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в Svelte-приложении на Webpack 5.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
Пример конфига:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "svelte@webpack",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта: генерация запускается через `npx`.
|
||||
|
||||
Добавьте команды генерации в `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "webpack serve --mode development",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "webpack --mode production"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт Svelte-компонент `AppIcon`.
|
||||
|
||||
Создайте `assets/app-icons/index.js`:
|
||||
|
||||
```js
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Используйте компонент в приложении:
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
import { AppIcon } from '../assets/app-icons/index.js'
|
||||
</script>
|
||||
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width="24"
|
||||
height="24"
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style="color: #334155; --icon-color-2: #f59e0b"
|
||||
/>
|
||||
```
|
||||
|
||||
Generated-компонент является нативным `.svelte`-файлом. Обычное правило `svelte-loader` должно обрабатывать `.svelte`-файлы в `assets`:
|
||||
|
||||
```js
|
||||
{
|
||||
test: /\.svelte$/,
|
||||
use: {
|
||||
loader: 'svelte-loader',
|
||||
options: { emitCss: false },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Webpack 5 обрабатывает asset URL из компонента и выпускает `sprite.svg` отдельным production asset.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице, позволяет проверить их отображение, изменить цвета и посмотреть связанные CSS-переменные. Он нужен только для разработки и устанавливается отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Добавьте Viewer в Svelte-компонент, используемый только при разработке:
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
|
||||
const sources = [
|
||||
() => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
|
||||
]
|
||||
|
||||
function connectViewer(node) {
|
||||
node.sources = sources
|
||||
}
|
||||
</script>
|
||||
|
||||
<gromlab-sprite-viewer
|
||||
use:connectViewer
|
||||
viewer-title="Иконки проекта"
|
||||
></gromlab-sprite-viewer>
|
||||
```
|
||||
|
||||
Запустите `npm run dev` и откройте страницу с Viewer. Не импортируйте этот отладочный компонент из production entry.
|
||||
@@ -0,0 +1,91 @@
|
||||
# SVG-спрайт для SvelteKit на Vite
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в SvelteKit-приложении на Vite.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
Пример конфига:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "sveltekit@vite",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта: генерация запускается через `npx`.
|
||||
|
||||
Добавьте команды генерации в `package.json`. Сгенерированные файлы по умолчанию исключены из Git, поэтому `predev` и `prebuild` пересобирают спрайт перед каждым запуском и сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "vite dev",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "vite build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт SSR-safe Svelte-компонент `AppIcon`.
|
||||
|
||||
Создайте `assets/app-icons/index.js`:
|
||||
|
||||
```js
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Используйте компонент в `src/routes/+page.svelte`:
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
import { AppIcon } from '../../assets/app-icons/index.js'
|
||||
</script>
|
||||
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width="24"
|
||||
height="24"
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style="color: #334155; --icon-color-2: #f59e0b"
|
||||
/>
|
||||
```
|
||||
|
||||
Свойство `icon` принимает имена исходных SVG без расширения. В компоненте нет browser-only инициализации, поэтому страница может рендериться на сервере. Vite выпускает `sprite.svg` отдельным production asset.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице, позволяет проверить их отображение, изменить цвета и посмотреть связанные CSS-переменные. Он нужен только для разработки и устанавливается отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Создайте отладочный route, например `src/routes/svg-sprite/+page.svelte`. Загружайте custom element из action, чтобы регистрация выполнялась только в браузере:
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
const sources = [
|
||||
() => import('../../../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
|
||||
]
|
||||
|
||||
function connectViewer(node) {
|
||||
void import('@gromlab/svg-sprites/viewer/element').then(() => {
|
||||
node.sources = sources
|
||||
node.viewerTitle = 'Иконки проекта'
|
||||
})
|
||||
}
|
||||
</script>
|
||||
|
||||
<gromlab-sprite-viewer use:connectViewer></gromlab-sprite-viewer>
|
||||
```
|
||||
|
||||
Запустите `npm run dev` и откройте `/svg-sprite`. Action не выполняется во время SSR.
|
||||
@@ -0,0 +1,105 @@
|
||||
# SVG-спрайт для Vue на Vite
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в Vue-приложении на Vite.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
Пример конфига:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "vue@vite",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта: генерация запускается через `npx`.
|
||||
|
||||
Добавьте команды генерации в `package.json`. Сгенерированные файлы по умолчанию исключены из Git, поэтому `predev` и `prebuild` пересобирают спрайт перед каждым запуском и сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "vite",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "vue-tsc --noEmit && vite build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт Vue-компонент `AppIcon`.
|
||||
|
||||
Создайте точку входа `assets/app-icons/index.ts`:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Используйте компонент в приложении:
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { AppIcon } from '../assets/app-icons'
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width="24"
|
||||
height="24"
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style="color: #334155; --icon-color-2: #f59e0b"
|
||||
/>
|
||||
</template>
|
||||
```
|
||||
|
||||
Свойство `icon` принимает имена исходных SVG без расширения. Монохромная иконка наследует `color`, а цвета многоцветной переопределяются через `--icon-color-N`.
|
||||
|
||||
Vite сам подключает стили компонента и добавляет `sprite.svg` в итоговую сборку.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице, позволяет проверить их отображение, изменить цвета и посмотреть связанные CSS-переменные. Он нужен только для разработки и устанавливается отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Создайте `svg-sprite.html` в корне проекта:
|
||||
|
||||
```html
|
||||
<!doctype html>
|
||||
<html lang="ru">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Иконки проекта</title>
|
||||
</head>
|
||||
<body>
|
||||
<gromlab-sprite-viewer viewer-title="Иконки проекта"></gromlab-sprite-viewer>
|
||||
<script type="module" src="/src/svg-sprite-debug.ts"></script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
Создайте `src/svg-sprite-debug.ts`:
|
||||
|
||||
```ts
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
import type { SpriteViewerElement } from '@gromlab/svg-sprites/viewer'
|
||||
import spriteManifest from '../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'
|
||||
|
||||
const viewer = document.querySelector<SpriteViewerElement>('gromlab-sprite-viewer')!
|
||||
viewer.sources = [spriteManifest]
|
||||
```
|
||||
|
||||
Запустите `npm run dev` и откройте `/svg-sprite.html`.
|
||||
|
||||
Viewer не требуется для работы `AppIcon` и не подключается к основному коду приложения.
|
||||
@@ -0,0 +1,126 @@
|
||||
# SVG-спрайт для Vue на Webpack 5
|
||||
|
||||
Инструкция по быстрому созданию SVG-спрайта в Vue-приложении на Webpack 5.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Выберите каталог для будущего SVG-спрайта, например `assets/app-icons`, и создайте в нём `svg-sprite.config.json`. В `input` укажите путь к существующим SVG относительно файла конфигурации. Перемещать или копировать иконки не требуется.
|
||||
|
||||
Пример конфига:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "vue@webpack",
|
||||
"name": "app",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
Пакет не нужно добавлять в зависимости проекта: генерация запускается через `npx`.
|
||||
|
||||
Добавьте команды генерации в `package.json`. Сгенерированные файлы по умолчанию исключены из Git, поэтому `predev` и `prebuild` пересобирают спрайт перед каждым запуском и сборкой:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
|
||||
"predev": "npm run sprites",
|
||||
"dev": "webpack serve --mode development",
|
||||
"prebuild": "npm run sprites",
|
||||
"build": "webpack --mode production"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Использование спрайта
|
||||
|
||||
Значение `name: "app"` создаёт Vue-компонент `AppIcon`. Создайте `assets/app-icons/index.js`:
|
||||
|
||||
```js
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Используйте компонент в приложении:
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import { AppIcon } from '../assets/app-icons/index.js'
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<AppIcon
|
||||
icon="icon-name"
|
||||
width="24"
|
||||
height="24"
|
||||
role="img"
|
||||
aria-label="Готово"
|
||||
style="color: #334155; --icon-color-2: #f59e0b"
|
||||
/>
|
||||
</template>
|
||||
```
|
||||
|
||||
Свойство `icon` принимает имена исходных SVG без расширения. Монохромная иконка наследует `color`, а цвета многоцветной переопределяются через `--icon-color-N`.
|
||||
|
||||
Компонент использует CSS Modules. Если проект ещё не обрабатывает их, установите `style-loader` и `css-loader`, затем добавьте правило с default export:
|
||||
|
||||
```bash
|
||||
npm install --save-dev style-loader css-loader
|
||||
```
|
||||
|
||||
```js
|
||||
{
|
||||
test: /\.module\.css$/i,
|
||||
use: [
|
||||
'style-loader',
|
||||
{
|
||||
loader: 'css-loader',
|
||||
options: { modules: { namedExport: false } },
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
Webpack 5 сам добавляет `sprite.svg` в итоговую сборку.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
Viewer показывает все иконки на одной странице, позволяет проверить их отображение, изменить цвета и посмотреть связанные CSS-переменные. Он нужен только для разработки и устанавливается отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Добавьте Viewer в Vue-компонент, подключаемый только при разработке:
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
|
||||
const sources = [
|
||||
() => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
|
||||
]
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<gromlab-sprite-viewer
|
||||
:sources="sources"
|
||||
viewer-title="Иконки проекта"
|
||||
/>
|
||||
</template>
|
||||
```
|
||||
|
||||
Настройте Vue Loader так, чтобы `gromlab-sprite-viewer` считался custom element:
|
||||
|
||||
```js
|
||||
{
|
||||
test: /\.vue$/,
|
||||
loader: 'vue-loader',
|
||||
options: {
|
||||
compilerOptions: {
|
||||
isCustomElement: (tag) => tag === 'gromlab-sprite-viewer',
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Покажите компонент Viewer на странице разработки. Viewer не требуется для работы `AppIcon`.
|
||||
@@ -0,0 +1,183 @@
|
||||
# Программный API
|
||||
|
||||
[Индекс документации](../README.md)
|
||||
|
||||
Пакет распространяется как ESM и предоставляет единый Node.js API генерации. Framework-neutral Viewer находится в `@gromlab/svg-sprites/viewer`, auto-register entry — в `@gromlab/svg-sprites/viewer/element`, React bridge — в `@gromlab/svg-sprites/react`.
|
||||
|
||||
## `generateSprite`
|
||||
|
||||
```ts
|
||||
import { generateSprite } from '@gromlab/svg-sprites'
|
||||
|
||||
const result = await generateSprite(
|
||||
'src/ui/file-manager/svg-sprite/svg-sprite.config.ts',
|
||||
)
|
||||
```
|
||||
|
||||
Результат содержит имя и mode спрайта, количество иконок и абсолютные filesystem paths:
|
||||
|
||||
```ts
|
||||
result.name
|
||||
result.mode
|
||||
result.target
|
||||
result.iconCount
|
||||
result.rootDir
|
||||
result.generatedDir
|
||||
result.spritePath
|
||||
result.manifestPath
|
||||
```
|
||||
|
||||
Next.js modes дополнительно возвращают `router` и `bundler`. `standalone@server`
|
||||
возвращает `target: 'server'`; его `spritePath` указывает на стандартный
|
||||
content-addressed profile, а `manifestPath` — на server manifest.
|
||||
|
||||
Для static standalone mode `result.spritePath` можно использовать в build-скрипте,
|
||||
чтобы опубликовать SVG по URL приложения:
|
||||
|
||||
```ts
|
||||
import { copyFile } from 'node:fs/promises'
|
||||
|
||||
const result = await generateSprite('src/sprite/svg-sprite.config.ts', {
|
||||
mode: 'standalone',
|
||||
})
|
||||
await copyFile(result.spritePath, 'dist/app-icons/sprite.svg')
|
||||
```
|
||||
|
||||
`spritePath` является filesystem path, а не browser URL. Deployment-neutral JSON
|
||||
manifest доступен через `result.manifestPath` и копируется независимо от SVG.
|
||||
|
||||
Первый аргумент принимает абсолютный или относительный путь к config-файлу с любым именем и расширением `.ts`, `.js` или `.json`. Каталог вместо файла включает config-less режим: корнем sprite-модуля становится этот каталог.
|
||||
|
||||
Второй аргумент содержит необязательные overrides и всегда имеет приоритет над конфигом:
|
||||
|
||||
```ts
|
||||
await generateSprite('src/ui/file-manager/svg-sprite/custom-config.json', {
|
||||
mode: 'react@webpack',
|
||||
name: 'documents',
|
||||
input: ['./assets', '../../shared/search.svg'],
|
||||
transform: {
|
||||
addTransition: false,
|
||||
},
|
||||
generatedNotice: false,
|
||||
})
|
||||
```
|
||||
|
||||
Порядок разрешения настроек:
|
||||
|
||||
```text
|
||||
defaults → config → API overrides
|
||||
```
|
||||
|
||||
Для полностью программной генерации передайте каталог и все обязательные настройки через overrides:
|
||||
|
||||
```ts
|
||||
await generateSprite('src/ui/file-manager/svg-sprite', {
|
||||
mode: 'react@vite',
|
||||
name: 'file-manager',
|
||||
input: [
|
||||
'../../shared/search.svg',
|
||||
'../../shared/settings.svg',
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
## Конфигурация
|
||||
|
||||
```ts
|
||||
import { defineSpriteConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default defineSpriteConfig({
|
||||
mode: 'react@vite',
|
||||
name: 'file-manager',
|
||||
description: 'Иконки файлового менеджера',
|
||||
input: ['./icons', '../../shared/check.svg'],
|
||||
transform: {
|
||||
removeSize: true,
|
||||
replaceColors: true,
|
||||
addTransition: true,
|
||||
},
|
||||
generatedNotice: true,
|
||||
})
|
||||
```
|
||||
|
||||
`input` принимает одну папку, SVG-файл или glob-паттерн либо массив, объединяющий такие источники. Если поле не задано, используется `./icons`; относительные пути считаются от папки с конфигом.
|
||||
|
||||
`defineSpriteConfig` является identity helper для TypeScript autocomplete. JS может экспортировать тот же объект через `export default`, а JSON содержит объект непосредственно.
|
||||
|
||||
Публичные типы `ServerSvgInput`, `ServerSpriteManifest`, `ServerSpriteAsset` и
|
||||
`SpriteCompileProfile` описывают inputs и release data для `standalone@server`.
|
||||
Consumer использует тот же API с `source: 'remote'` и одним local path или HTTP(S)
|
||||
URL manifest в `input`.
|
||||
|
||||
## Специализированные обёртки
|
||||
|
||||
Специализированные функции доступны как обёртки над `generateSprite`:
|
||||
|
||||
```ts
|
||||
import { generateNextSprite, generateReactSprite } from '@gromlab/svg-sprites'
|
||||
|
||||
await generateReactSprite('path/to/config.ts', 'vite')
|
||||
await generateNextSprite('path/to/config.ts', {
|
||||
router: 'app',
|
||||
bundler: 'turbopack',
|
||||
})
|
||||
```
|
||||
|
||||
Явно переданный target перекрывает `mode` из файла. Для нового кода используйте `generateSprite`.
|
||||
|
||||
## Config API
|
||||
|
||||
```ts
|
||||
import {
|
||||
isSpriteMode,
|
||||
loadSpriteConfig,
|
||||
resolveSpriteConfig,
|
||||
resolveSpriteConfigSource,
|
||||
validateSpriteConfig,
|
||||
} from '@gromlab/svg-sprites'
|
||||
```
|
||||
|
||||
- `isSpriteMode(value)` проверяет, является ли значение поддерживаемым exact mode.
|
||||
- `loadSpriteConfig(file)` загружает явно указанный `.ts`, `.js` или `.json` файл.
|
||||
- `resolveSpriteConfigSource(source)` разрешает путь как config-файл или config-less каталог.
|
||||
- `validateSpriteConfig(value)` выполняет runtime-валидацию объекта.
|
||||
- `resolveSpriteConfig(root, config, overrides)` объединяет значения, добавляет defaults и разрешает пути относительно `root`.
|
||||
|
||||
## Низкоуровневый compiler
|
||||
|
||||
```ts
|
||||
import {
|
||||
compileSprite,
|
||||
compileSpriteContent,
|
||||
createShapeTransform,
|
||||
} from '@gromlab/svg-sprites'
|
||||
```
|
||||
|
||||
Эти функции предназначены для собственного orchestration. Стандартная генерация должна выполняться через `generateSprite`.
|
||||
|
||||
## Viewer runtime
|
||||
|
||||
```ts
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
import type { SpriteViewerElement } from '@gromlab/svg-sprites/viewer'
|
||||
```
|
||||
|
||||
Browser entry регистрирует `<gromlab-sprite-viewer>`. Bare standalone также может загрузить самостоятельный `dist/viewer-element.js` без bundler.
|
||||
|
||||
Для ручной регистрации импортируйте runtime без auto-register entry:
|
||||
|
||||
```ts
|
||||
import { defineSpriteViewerElement } from '@gromlab/svg-sprites/viewer'
|
||||
|
||||
defineSpriteViewerElement()
|
||||
```
|
||||
|
||||
Этот entry также экспортирует типы `SpriteViewerElement`, `SpriteViewerManifest`, `SpriteViewerSource`, `SpriteViewerSources` и связанные типы manifest и loaders.
|
||||
|
||||
React bridge сохраняет компонентный API:
|
||||
|
||||
```tsx
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
```
|
||||
|
||||
`SpriteViewer` принимает generated manifests, remote standalone sources, lazy loaders или результат `import.meta.glob`. React entry содержит `'use client'` и предназначен для debug-инструментов; production-компоненты импортируются из локальных sprite-модулей приложения.
|
||||
@@ -0,0 +1,716 @@
|
||||
# Технический справочник
|
||||
|
||||
[Индекс документации](../README.md)
|
||||
|
||||
[Конфигурация JSON, JavaScript и TypeScript](../configuration.md)
|
||||
|
||||
Справочник по конфигурации, generated API и поведению `@gromlab/svg-sprites`. Пошаговую установку смотрите в руководстве для вашего стека:
|
||||
|
||||
- [Bare standalone](../guides/standalone.md)
|
||||
- [Standalone + Vite](../guides/standalone-vite.md)
|
||||
- [Standalone + Webpack 5](../guides/standalone-webpack.md)
|
||||
- [React + Vite](../guides/react-vite.md)
|
||||
- [React + Webpack 5](../guides/react-webpack.md)
|
||||
- [Next.js App Router + Turbopack](../guides/next-app-turbopack.md)
|
||||
- [Next.js App Router + Webpack](../guides/next-app-webpack.md)
|
||||
- [Next.js Pages Router + Turbopack](../guides/next-pages-turbopack.md)
|
||||
- [Next.js Pages Router + Webpack](../guides/next-pages-webpack.md)
|
||||
- [Vue + Vite](../guides/vue-vite.md)
|
||||
- [Vue + Webpack](../guides/vue-webpack.md)
|
||||
- [Nuxt + Vite](../guides/nuxt-vite.md)
|
||||
- [Nuxt + Webpack](../guides/nuxt-webpack.md)
|
||||
- [Svelte + Vite](../guides/svelte-vite.md)
|
||||
- [Svelte + Webpack](../guides/svelte-webpack.md)
|
||||
- [SvelteKit + Vite](../guides/sveltekit-vite.md)
|
||||
- [Angular application builder](../guides/angular-application.md)
|
||||
- [Angular + Webpack](../guides/angular-webpack.md)
|
||||
- [Astro + Vite](../guides/astro-vite.md)
|
||||
- [Solid + Vite](../guides/solid-vite.md)
|
||||
- [Solid + Webpack](../guides/solid-webpack.md)
|
||||
- [SolidStart + Vite](../guides/solid-start-vite.md)
|
||||
- [Preact + Vite](../guides/preact-vite.md)
|
||||
- [Preact + Webpack](../guides/preact-webpack.md)
|
||||
- [Qwik + Vite](../guides/qwik-vite.md)
|
||||
- [Lit + Vite](../guides/lit-vite.md)
|
||||
- [Lit + Webpack](../guides/lit-webpack.md)
|
||||
- [Alpine.js + Vite](../guides/alpine-vite.md)
|
||||
- [Alpine.js + Webpack](../guides/alpine-webpack.md)
|
||||
|
||||
## Требования
|
||||
|
||||
- Node.js 18 или новее;
|
||||
- пакет распространяется как ESM и подключается через `import`;
|
||||
- React 18 или 19 требуется только для React/Next generated-компонентов и `@gromlab/svg-sprites/react`;
|
||||
- для типизации package exports используйте TypeScript 5+ с `moduleResolution: "bundler"`, `"node16"` или `"nodenext"`.
|
||||
|
||||
Для генерации не нужна dependency проекта. Запускайте CLI через `npx`:
|
||||
|
||||
```bash
|
||||
npx --yes @gromlab/svg-sprites path/to/svg-sprite.config.json
|
||||
```
|
||||
|
||||
Устанавливайте пакет как development dependency, только если проекту нужны
|
||||
Viewer, типы конфига или программный API:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
## CLI и режимы генерации
|
||||
|
||||
Для генерации CLI принимает ровно один путь: явно выбранный config-файл либо каталог для config-less генерации:
|
||||
|
||||
```text
|
||||
svg-sprites [options] <config-file-or-directory>
|
||||
```
|
||||
|
||||
| Среда | Mode |
|
||||
|---|---|
|
||||
| Static HTML / собственная публикация | `standalone` |
|
||||
| Standalone + Vite | `standalone@vite` |
|
||||
| Standalone + Webpack 5 | `standalone@webpack` |
|
||||
| Server release | `standalone@server` |
|
||||
| React + Vite | `react@vite` |
|
||||
| React + Webpack 5 | `react@webpack` |
|
||||
| Vue + Vite | `vue@vite` |
|
||||
| Vue + Webpack | `vue@webpack` |
|
||||
| Nuxt + Vite | `nuxt@vite` |
|
||||
| Nuxt + Webpack | `nuxt@webpack` |
|
||||
| Svelte + Vite | `svelte@vite` |
|
||||
| Svelte + Webpack | `svelte@webpack` |
|
||||
| SvelteKit + Vite | `sveltekit@vite` |
|
||||
| Angular application builder | `angular@application` |
|
||||
| Angular + Webpack | `angular@webpack` |
|
||||
| Astro + Vite | `astro@vite` |
|
||||
| Solid + Vite | `solid@vite` |
|
||||
| Solid + Webpack | `solid@webpack` |
|
||||
| SolidStart + Vite | `solid-start@vite` |
|
||||
| Preact + Vite | `preact@vite` |
|
||||
| Preact + Webpack | `preact@webpack` |
|
||||
| Qwik + Vite | `qwik@vite` |
|
||||
| Lit + Vite | `lit@vite` |
|
||||
| Lit + Webpack | `lit@webpack` |
|
||||
| Alpine.js + Vite | `alpine@vite` |
|
||||
| Alpine.js + Webpack | `alpine@webpack` |
|
||||
| Next.js App Router + Turbopack | `next@app/turbopack` |
|
||||
| Next.js App Router + Webpack 5 | `next@app/webpack` |
|
||||
| Next.js Pages Router + Turbopack | `next@pages/turbopack` |
|
||||
| Next.js Pages Router + Webpack 5 | `next@pages/webpack` |
|
||||
|
||||
Config-файл может иметь любое имя и расширение `.ts`, `.js` или `.json`. CLI не ищет конфиг по соглашению: файл нужно передать явно. В руководствах используется рекомендуемое имя `svg-sprite.config.json`.
|
||||
|
||||
Если передан каталог, все настройки берутся из CLI. Если передан config-файл, CLI-параметры перекрывают значения файла. Общий порядок: `defaults → config → CLI`.
|
||||
|
||||
`--help` и `-h` выводят справку без обязательного пути. Для генерации доступны `--mode`, `--source <local|remote>`, `--name`, `--description`, повторяемый `--input <path-or-glob>`, а также пары `--remove-size`/`--no-remove-size`, `--replace-colors`/`--no-replace-colors`, `--add-transition`/`--no-add-transition` и `--generated-notice`/`--no-generated-notice`. Переданные transform-флаги перекрывают отдельные поля, а хотя бы один `--input` полностью заменяет значение `input` из config.
|
||||
|
||||
В CLI заключайте glob-паттерны в одинарные кавычки, чтобы shell не раскрыл их до запуска генератора:
|
||||
|
||||
```bash
|
||||
svg-sprites --input './icons/**/*.svg' --input '!./icons/legacy/**' svg-sprite.config.ts
|
||||
```
|
||||
|
||||
Mode должен соответствовать способу публикации приложения. Bare `standalone` оставляет публичный URL приложению; Vite и Webpack modes генерируют bundler-specific подключение SVG asset.
|
||||
|
||||
## Единая конфигурация
|
||||
|
||||
Каждый config-файл описывает один независимый спрайт.
|
||||
|
||||
```ts
|
||||
import { defineSpriteConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default defineSpriteConfig({
|
||||
mode: 'next@app/turbopack',
|
||||
name: 'app',
|
||||
description: 'Общие иконки приложения',
|
||||
input: [
|
||||
'./local-icons',
|
||||
'../../assets/icons/*.svg',
|
||||
'!../../assets/icons/deprecated-*.svg',
|
||||
],
|
||||
transform: {
|
||||
removeSize: true,
|
||||
replaceColors: true,
|
||||
addTransition: true,
|
||||
},
|
||||
generatedNotice: true,
|
||||
})
|
||||
```
|
||||
|
||||
| Опция | Тип | По умолчанию | Назначение |
|
||||
|---|---|---|---|
|
||||
| `mode` | `SpriteMode` | Нет | Режим генерации; можно передать через CLI/API |
|
||||
| `source` | `local \| remote` | `local` | Исходные SVG либо готовый server manifest |
|
||||
| `name` | `string` | Выводится из каталога | Имя спрайта; в modes с компонентом также задаёт имя компонента и публичных типов |
|
||||
| `description` | `string` | Нет | Описание для типов и debug manifest |
|
||||
| `input` | `SpriteInput \| SpriteInput[]` | `./icons` | Локальные SVG sources, server HTTP descriptors либо один remote manifest в зависимости от mode и source |
|
||||
| `transform` | `TransformOptions` | Все включены | Настройки подготовки SVG |
|
||||
| `generatedNotice` | `boolean` | `true` | Полное или короткое предупреждение в generated-файлах |
|
||||
|
||||
При `source: 'remote'` поле `input` содержит один local path или HTTP(S) URL
|
||||
manifest, созданного `standalone@server`. Remote consumer config может содержать
|
||||
только `mode`, `source` и `input`: name, description, transforms и generated notice
|
||||
проверяются и наследуются из server manifest. До codegen генератор скачивает profile,
|
||||
необходимый exact consumer mode, и проверяет его SHA-256 и размер. Runtime-зависимости
|
||||
от server manifest нет.
|
||||
|
||||
### Имя спрайта
|
||||
|
||||
`name` записывается в kebab-case и должно начинаться с латинской буквы:
|
||||
|
||||
```text
|
||||
app → AppIcon
|
||||
file-manager → FileManagerIcon
|
||||
```
|
||||
|
||||
Если `name` не задано, генератор преобразует имя каталога в kebab-case. Для каталога с именем `svg-sprite` или `svg-sprites` используется имя родительского каталога.
|
||||
|
||||
### Источники иконок
|
||||
|
||||
`SpriteConfig.input` является необязательным и имеет тип `string | string[]`. Если поле отсутствует, источником служит папка `./icons` относительно папки конфига. В config-less режиме относительные пути считаются от каталога, переданного CLI или API.
|
||||
|
||||
Каждая строка без префикса `!` может быть путём к конкретной папке, конкретному файлу `.svg` или glob-паттерном. Папка включает только непосредственные дочерние `*.svg`. Для рекурсивного обхода вложенных каталогов укажите явный паттерн, например `icons/**/*.svg`.
|
||||
|
||||
Массив объединяет все включающие источники. Паттерн с префиксом `!` глобально исключает совпадения из общего результата независимо от того, какой источник их добавил.
|
||||
|
||||
Поддерживается следующий glob-синтаксис:
|
||||
|
||||
| Синтаксис | Значение |
|
||||
|---|---|
|
||||
| `*` | Любые символы внутри одного сегмента пути |
|
||||
| `**` | Любое число вложенных каталогов |
|
||||
| `?` | Один символ внутри сегмента пути |
|
||||
| `{a,b}` | Одна из альтернатив |
|
||||
| `[abc]` | Один символ из набора или диапазона |
|
||||
| `!pattern` | Исключение совпадений из всего объединённого input |
|
||||
|
||||
Каждый включающий источник или паттерн должен найти хотя бы один SVG, иначе генерация завершается ошибкой. Повторяющиеся пути удаляются, а итоговый список файлов детерминированно сортируется. Разные SVG с одинаковым basename по-прежнему считаются конфликтом, потому что basename задаёт публичное имя иконки.
|
||||
|
||||
### Server SVG inputs
|
||||
|
||||
`standalone@server` принимает те же local strings и HTTP(S) descriptors в массиве
|
||||
`input`:
|
||||
|
||||
```ts
|
||||
{
|
||||
name: 'brand-logo',
|
||||
url: 'https://assets.example.com/brand-logo.svg',
|
||||
sha256: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
|
||||
}
|
||||
```
|
||||
|
||||
`name` становится публичным именем иконки. Необязательный `sha256` проверяется по
|
||||
скачанным байтам. URL credentials и активное SVG-содержимое, включая scripts,
|
||||
event handlers, `foreignObject` и doctype, запрещены. Один HTTP source ограничен
|
||||
2 MiB, все источники вместе — 25 MiB, timeout запроса равен 15 секундам. Local и
|
||||
HTTP entries используют единое пространство имён, поэтому duplicate icon names
|
||||
завершают генерацию с ошибкой.
|
||||
|
||||
## Generated-модуль
|
||||
|
||||
После генерации React- или Next.js-каталог спрайта выглядит так:
|
||||
|
||||
```text
|
||||
app-icons/
|
||||
├── .gitignore
|
||||
├── svg-sprite.config.json
|
||||
├── index.ts # необязательный пользовательский barrel
|
||||
└── .svg-sprite/
|
||||
├── index.js
|
||||
├── index.d.ts
|
||||
├── icon-data.js
|
||||
├── icon-data.d.ts
|
||||
├── sprite.svg
|
||||
├── svg-sprite.manifest.js
|
||||
├── svg-sprite.manifest.d.ts
|
||||
└── react/
|
||||
├── react-component.js
|
||||
├── react-component.d.ts
|
||||
└── react-component.module.css
|
||||
```
|
||||
|
||||
| Файл | Назначение |
|
||||
|---|---|
|
||||
| `.svg-sprite/index.js` | Mode-specific production facade и runtime-список имён |
|
||||
| `.svg-sprite/index.d.ts` | Публичные декларации facade, компонента и union-типа имён |
|
||||
| `.svg-sprite/svg-sprite.manifest.js` | Debug metadata и URL asset для `SpriteViewer` |
|
||||
| `.svg-sprite/sprite.svg` | Собранный SVG-спрайт |
|
||||
| `.svg-sprite/react/react-component.js` | Runtime React-компонента без TypeScript и JSX |
|
||||
| `.svg-sprite/react/react-component.d.ts` | Props, style и declaration React-компонента |
|
||||
| `.svg-sprite/react/react-component.module.css` | Стили конкретной React-реализации |
|
||||
| `.svg-sprite/icon-data.js` | Runtime-список имён и внутренние IDs |
|
||||
| `.svg-sprite/*.d.ts` | TypeScript-декларации соответствующих JS-модулей |
|
||||
|
||||
Standalone-контракты не создают каталог `react/`. Bare `standalone` содержит только
|
||||
runtime asset и deployment-neutral manifest data:
|
||||
|
||||
```text
|
||||
.svg-sprite/
|
||||
├── sprite.svg
|
||||
└── svg-sprite.manifest.json
|
||||
```
|
||||
|
||||
`standalone@vite` и `standalone@webpack` дополнительно создают `index.*`,
|
||||
`icon-data.*` и resolved `svg-sprite.manifest.*`. Их facade содержит нативный
|
||||
generated Web Component без внешних runtime-зависимостей. Bare `standalone`
|
||||
намеренно не создаёт JavaScript-компонент.
|
||||
|
||||
`standalone@server` создаёт готовый к публикации release без JavaScript runtime и
|
||||
`.gitignore`:
|
||||
|
||||
```text
|
||||
.svg-sprite/
|
||||
├── sprite.<content-hash>.svg
|
||||
├── sprite-root-viewbox.<content-hash>.svg
|
||||
└── svg-sprite.manifest.json
|
||||
```
|
||||
|
||||
Manifest описывает оба compile profiles через relative `href`, полный SHA-256 и
|
||||
размер в байтах. Публикуйте весь каталог атомарно; consumer разрешает каждый profile
|
||||
относительно URL или local path manifest.
|
||||
|
||||
`.svg-sprite` полностью управляется генератором и при каждой генерации заменяется целиком. Любые добавленные в него файлы будут удалены. Пользовательские файлы размещайте рядом, например в корневом `index.ts`:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
## Standalone Web Component и TypeScript
|
||||
|
||||
В modes `standalone@vite` и `standalone@webpack` спрайт с `name: 'app'`
|
||||
экспортирует функцию регистрации `defineAppIconElement()` и tag `<app-icon>`:
|
||||
|
||||
```ts
|
||||
import { defineAppIconElement } from '@/ui/app-icons'
|
||||
|
||||
defineAppIconElement()
|
||||
```
|
||||
|
||||
После регистрации элемент можно использовать в HTML:
|
||||
|
||||
```html
|
||||
<app-icon icon="search" aria-hidden="true"></app-icon>
|
||||
|
||||
<app-icon
|
||||
icon="settings"
|
||||
role="img"
|
||||
aria-label="Настройки"
|
||||
></app-icon>
|
||||
```
|
||||
|
||||
Компонент рендерит `<svg><use>` в открытом Shadow DOM, сам выбирает внутренний
|
||||
ID и `viewBox`, а URL asset получает через соответствующий Vite или Webpack
|
||||
механизм. Размер host по умолчанию равен `1em × 1em`; `class`, `style`, `color`
|
||||
и `--icon-color-N` задаются обычным CSS.
|
||||
|
||||
Generated `HTMLElementTagNameMap` типизирует property API:
|
||||
|
||||
```ts
|
||||
const icon = document.createElement('app-icon')
|
||||
|
||||
icon.icon = 'search'
|
||||
icon.icon = 'unknown' // ошибка TypeScript
|
||||
```
|
||||
|
||||
Значения атрибутов в обычной HTML-разметке TypeScript не проверяет. Поэтому
|
||||
неизвестный `icon="unknown"` дополнительно проверяется в runtime: компонент
|
||||
скрывает внутренний SVG и сообщает об ошибке, не создавая fragment
|
||||
`#undefined`. Повторный вызов `defineAppIconElement()` безопасен для того же
|
||||
спрайта; конфликт с другим элементом под tag `<app-icon>` завершается ошибкой.
|
||||
|
||||
## React-компонент и TypeScript
|
||||
|
||||
Спрайт с `name: 'app'` экспортирует:
|
||||
|
||||
```ts
|
||||
export { AppIcon, appIconNames }
|
||||
export type { AppIconName, AppIconProps, AppIconStyle }
|
||||
```
|
||||
|
||||
### Имена иконок
|
||||
|
||||
Имена SVG-файлов становятся допустимыми значениями `icon`:
|
||||
|
||||
```tsx
|
||||
<AppIcon icon="search" />
|
||||
<AppIcon icon="unknown" /> // ошибка TypeScript
|
||||
```
|
||||
|
||||
Runtime-список содержит те же значения:
|
||||
|
||||
```ts
|
||||
import { appIconNames } from '@/ui/app-icons'
|
||||
|
||||
// readonly ['search', 'settings', 'user']
|
||||
```
|
||||
|
||||
Имена с пробелами и другими небезопасными для SVG ID символами остаются частью публичного API. Для внутреннего fragment ID генератор создаёт стабильный безопасный hash:
|
||||
|
||||
```text
|
||||
folder open.svg → icon="folder open" → id="icon-<stable-hash>"
|
||||
```
|
||||
|
||||
Для таких имён используйте generated-компонент или `id` из debug manifest, а не формируйте fragment ID вручную.
|
||||
|
||||
### SVG-атрибуты
|
||||
|
||||
По умолчанию компонент рендерит `<svg>` и принимает стандартные SVG-атрибуты:
|
||||
|
||||
```tsx
|
||||
<AppIcon
|
||||
icon="search"
|
||||
width={24}
|
||||
height={24}
|
||||
color="rebeccapurple"
|
||||
className="searchIcon"
|
||||
aria-label="Поиск"
|
||||
/>
|
||||
```
|
||||
|
||||
Компонент не добавляет accessibility-семантику автоматически. Передавайте подходящие `aria-*`, `role` или подпись в зависимости от назначения иконки.
|
||||
|
||||
### Обёртка
|
||||
|
||||
`wrapped` рендерит `<span>` с внутренним SVG. Остальные props в этом режиме относятся к `<span>`:
|
||||
|
||||
```tsx
|
||||
<AppIcon icon="search" wrapped className="iconWrapper" />
|
||||
```
|
||||
|
||||
### Типизированные CSS-переменные
|
||||
|
||||
`AppIconStyle` расширяет `CSSProperties` и поддерживает свойства вида `--icon-color-N`:
|
||||
|
||||
```tsx
|
||||
<AppIcon
|
||||
icon="user"
|
||||
style={{
|
||||
'--icon-color-1': '#2563eb',
|
||||
'--icon-color-2': '#dbeafe',
|
||||
}}
|
||||
/>
|
||||
```
|
||||
|
||||
## Множественные спрайты
|
||||
|
||||
Каждый каталог с конфигом создаёт независимый mode-specific контракт. Framework modes создают нативный компонент и declarations, standalone bundler modes — Web Component и declarations, а bare `standalone` — SVG и JSON manifest:
|
||||
|
||||
```text
|
||||
app-icons → AppIcon → общие иконки
|
||||
analytics-icons → AnalyticsIcon → иконки страницы аналитики
|
||||
editor-icons → EditorIcon → иконки редактора
|
||||
```
|
||||
|
||||
Один исходный SVG можно добавить через `input` в несколько конфигураций. Копировать файл в каталоги каждого спрайта не требуется.
|
||||
|
||||
Для нескольких спрайтов добавьте отдельную CLI-команду для каждого каталога или объедините команды в общем npm script.
|
||||
|
||||
## Форматы и способы отображения
|
||||
|
||||
Все текущие modes создают формат `stack`.
|
||||
|
||||
| Формат | `<svg><use>` | `<img>` | CSS background |
|
||||
|---|---:|---:|---:|
|
||||
| `stack` | Да | Да | Да |
|
||||
|
||||
### Generated-компонент
|
||||
|
||||
Используйте generated native-компонент из guide выбранного exact mode. Он знает внутренние ID, формирует URL и предоставляет TypeScript API. Для React и Next.js это выглядит так:
|
||||
|
||||
```tsx
|
||||
<AppIcon icon="search" width={24} height={24} />
|
||||
```
|
||||
|
||||
Для `standalone@vite` и `standalone@webpack` используйте generated Web Component:
|
||||
|
||||
```html
|
||||
<app-icon icon="search" style="font-size: 24px"></app-icon>
|
||||
```
|
||||
|
||||
### Вручную через `<svg><use>`
|
||||
|
||||
Способ получения `spriteUrl` зависит от сборщика.
|
||||
|
||||
Static HTML после публикации `.svg-sprite/sprite.svg` приложением:
|
||||
|
||||
```html
|
||||
<svg aria-hidden="true">
|
||||
<use href="/assets/icons.svg#search"></use>
|
||||
</svg>
|
||||
```
|
||||
|
||||
Standalone Vite/Webpack предоставляет generated `getAppIconHref()` и mapping
|
||||
внутренних IDs. Не конструируйте fragment из небезопасного имени файла вручную.
|
||||
|
||||
Vite:
|
||||
|
||||
```ts
|
||||
import spriteUrl from './.svg-sprite/sprite.svg?no-inline'
|
||||
```
|
||||
|
||||
Webpack 5, Turbopack и Next.js:
|
||||
|
||||
```ts
|
||||
const spriteUrl = new URL('./.svg-sprite/sprite.svg', import.meta.url).href
|
||||
```
|
||||
|
||||
После получения URL используйте его в JSX:
|
||||
|
||||
```tsx
|
||||
<svg width="24" height="24" aria-label="Поиск">
|
||||
<use href={`${spriteUrl}#search`} />
|
||||
</svg>
|
||||
```
|
||||
|
||||
Для имён, небезопасных как SVG ID, используйте внутренний `id` из manifest.
|
||||
|
||||
### Через `<img>`
|
||||
|
||||
```tsx
|
||||
<img src={`${spriteUrl}#search`} width={24} height={24} alt="Поиск" />
|
||||
```
|
||||
|
||||
SVG внутри `<img>` изолирован от CSS страницы. `color` и `--icon-color-N` на внешнем элементе не изменяют его внутренние цвета.
|
||||
|
||||
### Через CSS
|
||||
|
||||
```css
|
||||
.icon {
|
||||
background: url('./.svg-sprite/sprite.svg#search') center / contain no-repeat;
|
||||
}
|
||||
```
|
||||
|
||||
Для одноцветного силуэта можно использовать mask:
|
||||
|
||||
```css
|
||||
.icon {
|
||||
background-color: currentColor;
|
||||
mask: url('./.svg-sprite/sprite.svg#search') center / contain no-repeat;
|
||||
}
|
||||
```
|
||||
|
||||
Mask не сохраняет исходные цвета, gradients и различия между `fill` и `stroke`.
|
||||
|
||||
Путь в CSS разрешается относительно самого CSS-файла. В примерах CSS-файл находится рядом с `svg-sprite.config.ts`.
|
||||
|
||||
## Assets и кеширование
|
||||
|
||||
Generated component или standalone facade передаёт SVG сборщику как отдельный asset:
|
||||
|
||||
- Vite использует статический импорт с `?no-inline`;
|
||||
- Webpack 5, Turbopack и Next.js используют `new URL(..., import.meta.url)`;
|
||||
- SVG path-данные не сериализуются в generated JavaScript.
|
||||
|
||||
Bare `standalone` не участвует в asset pipeline: приложение само копирует или
|
||||
публикует `sprite.svg` и отвечает за URL, версионирование и cache policy.
|
||||
|
||||
При стандартном именовании assets сборщик добавляет content hash:
|
||||
|
||||
```text
|
||||
/assets/sprite-<hash>.svg
|
||||
```
|
||||
|
||||
Это позволяет кешировать SVG отдельно от JavaScript. Изменение React-кода не меняет содержимое спрайта, а изменение иконок создаёт новую версию asset.
|
||||
|
||||
HTTP cache headers, CDN и `Cache-Control` настраиваются приложением или платформой размещения. Для Webpack имя итогового файла зависит от `assetModuleFilename` проекта.
|
||||
|
||||
## Трансформации SVG
|
||||
|
||||
Все трансформации включены по умолчанию и настраиваются независимо:
|
||||
|
||||
| Опция | Что делает |
|
||||
|---|---|
|
||||
| `removeSize` | Удаляет `width` и `height` с корневого `<svg>`, сохраняя существующий `viewBox` |
|
||||
| `replaceColors` | Заменяет найденные `fill` и `stroke` на `--icon-color-N` |
|
||||
| `addTransition` | Добавляет transitions для `fill` и `stroke` в цветные элементы и generated styles |
|
||||
|
||||
Чтобы отключить отдельную операцию:
|
||||
|
||||
```ts
|
||||
export default defineSpriteConfig({
|
||||
mode: 'next@app/turbopack',
|
||||
transform: {
|
||||
removeSize: false,
|
||||
replaceColors: false,
|
||||
addTransition: false,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
Исходные SVG не изменяются. Трансформации применяются только к содержимому generated-спрайта.
|
||||
|
||||
## Управление цветами
|
||||
|
||||
### Монохромные иконки
|
||||
|
||||
Если найден один цвет, fallback становится `currentColor`:
|
||||
|
||||
```svg
|
||||
stroke="var(--icon-color-1, currentColor)"
|
||||
```
|
||||
|
||||
Цвет задаётся через prop или CSS:
|
||||
|
||||
```tsx
|
||||
<AppIcon icon="search" color="rebeccapurple" />
|
||||
```
|
||||
|
||||
### Многоцветные иконки
|
||||
|
||||
Каждый уникальный цвет получает отдельную переменную с исходным fallback:
|
||||
|
||||
```svg
|
||||
fill="var(--icon-color-1, #798198)"
|
||||
fill="var(--icon-color-2, #ffffff)"
|
||||
fill="var(--icon-color-3, #129d9d)"
|
||||
```
|
||||
|
||||
Можно заменить только необходимые значения:
|
||||
|
||||
```css
|
||||
.icon {
|
||||
--icon-color-1: #4b5563;
|
||||
--icon-color-3: #14b8a6;
|
||||
}
|
||||
```
|
||||
|
||||
### Ограничения
|
||||
|
||||
- `none`, `transparent`, `inherit`, `unset` и `initial` не заменяются;
|
||||
- надёжнее всего обрабатываются цвета в атрибутах `fill`, `stroke` и inline `style`;
|
||||
- CSS-классы и внешние stylesheets внутри SVG не являются основным сценарием трансформации;
|
||||
- значения `url(#...)` могут быть заменены вместе с цветами, поэтому gradients и patterns требуют отдельного спрайта с `replaceColors: false`;
|
||||
- masks, filters и сложные внутренние CSS-правила требуют визуальной проверки;
|
||||
- CSS-переменные страницы доступны через `<svg><use>`, но не внутри `<img>` и CSS background.
|
||||
|
||||
Для сложной иконки можно отключить `replaceColors` в конфигурации отдельного спрайта.
|
||||
|
||||
## SpriteViewer
|
||||
|
||||
Viewer использует один Web Component с Shadow DOM для всех modes. React и будущие framework-компоненты являются bridge к этому же элементу, поэтому визуал и поведение не дублируются.
|
||||
|
||||
Bare `standalone` подключает самостоятельный browser bundle и передаёт URL JSON manifest и опубликованного SVG:
|
||||
|
||||
```html
|
||||
<script
|
||||
type="module"
|
||||
src="https://unpkg.com/@gromlab/svg-sprites@<version>/dist/viewer-element.js"
|
||||
></script>
|
||||
|
||||
<gromlab-sprite-viewer
|
||||
viewer-title="Иконки проекта"
|
||||
manifest-url="/app-icons/manifest.json"
|
||||
sprite-url="/app-icons/sprite.svg"
|
||||
></gromlab-sprite-viewer>
|
||||
```
|
||||
|
||||
`viewer-element.js` не имеет дополнительных runtime-файлов и может быть скопирован с остальными static assets для self-hosting.
|
||||
|
||||
`standalone@vite` и `standalone@webpack` регистрируют тот же элемент через npm entry и передают generated JS manifest через свойство `sources`:
|
||||
|
||||
```ts
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
import type { SpriteViewerElement } from '@gromlab/svg-sprites/viewer'
|
||||
import spriteManifest from './svg-sprite/.svg-sprite/svg-sprite.manifest.js'
|
||||
|
||||
const viewer = document.querySelector<SpriteViewerElement>('gromlab-sprite-viewer')!
|
||||
viewer.sources = [spriteManifest]
|
||||
```
|
||||
|
||||
React и Next.js сохраняют компонентный API:
|
||||
|
||||
```tsx
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
```
|
||||
|
||||
Он принимает готовые manifests, remote standalone sources, массив lazy loaders или record формата `import.meta.glob`.
|
||||
|
||||
Vite:
|
||||
|
||||
```tsx
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
import type { SpriteManifestModule } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = import.meta.glob<SpriteManifestModule>(
|
||||
'/src/**/svg-sprite/.svg-sprite/svg-sprite.manifest.js',
|
||||
)
|
||||
|
||||
export const IconsDebugPage = () => (
|
||||
<SpriteViewer sources={sources} title="Иконки проекта" />
|
||||
)
|
||||
```
|
||||
|
||||
Webpack и Next.js:
|
||||
|
||||
```tsx
|
||||
const sources = [
|
||||
() => import('@/ui/app-icons/.svg-sprite/svg-sprite.manifest.js'),
|
||||
() => import('@/features/analytics/icons/.svg-sprite/svg-sprite.manifest.js'),
|
||||
]
|
||||
|
||||
export const IconsDebugPage = () => (
|
||||
<SpriteViewer sources={sources} />
|
||||
)
|
||||
```
|
||||
|
||||
Viewer показывает группы, поиск, `viewBox`, CSS-переменные и fallback-цвета. Framework manifests получают вкладку своего framework, а также SVG, IMG и CSS; standalone manifests получают SVG, IMG и CSS. Цветовые значения можно менять в интерфейсе и сразу проверять результат.
|
||||
|
||||
### Тема Viewer
|
||||
|
||||
По умолчанию `colorTheme="auto"` следует `prefers-color-scheme`. Можно передать `light` или `dark` явно:
|
||||
|
||||
```tsx
|
||||
<SpriteViewer sources={sources} colorTheme="dark" />
|
||||
```
|
||||
|
||||
Для синхронизации с темой приложения:
|
||||
|
||||
```tsx
|
||||
<SpriteViewer
|
||||
sources={sources}
|
||||
colorTheme={appTheme}
|
||||
onColorThemeChange={setAppTheme}
|
||||
/>
|
||||
```
|
||||
|
||||
`@gromlab/svg-sprites/react` содержит `'use client'` и рендерит Web Component host; внутренний Shadow DOM создаётся после загрузки browser runtime. В Next.js App Router размещайте Viewer внутри отдельной Client Component boundary и используйте только на debug-маршруте или во внутреннем инструменте.
|
||||
|
||||
## Generated-файлы, Git и CI
|
||||
|
||||
Все modes, кроме bare `standalone`, создают локальный `.gitignore` для:
|
||||
|
||||
```text
|
||||
/.svg-sprite/
|
||||
```
|
||||
|
||||
Локальный `.gitignore` следует один раз добавить в репозиторий. Он исключает остальные generated-файлы, поэтому генерацию нужно запускать перед командами, которые импортируют sprite-модуль:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes @gromlab/svg-sprites src/ui/app-icons/svg-sprite.config.ts",
|
||||
"predev": "npm run sprites",
|
||||
"prebuild": "npm run sprites",
|
||||
"pretypecheck": "npm run sprites"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
CI должен выполнять generation script до сборки или проверки типов. Локальная установка package не нужна, если CI не использует Viewer, package-типы config или программный API.
|
||||
|
||||
Bare `standalone` не создаёт `.gitignore` и сохраняет пользовательский файл. Если после другого mode остался управляемый `.gitignore`, bare mode удалит его. В остальных modes генератор откажется перезаписать пользовательский `.gitignore` без generated marker. Корневой `index.ts` остаётся пользовательским и может переэкспортировать generated API.
|
||||
|
||||
## Диагностика
|
||||
|
||||
- Для всех modes, кроме bare `standalone`: если нет `.svg-sprite/index.js`, запустите generation script до импорта generated-модуля.
|
||||
- Не найден источник: передайте существующий config-файл или каталог sprite-модуля.
|
||||
- Не указан mode: добавьте `mode` в config либо передайте `--mode`.
|
||||
- Иконка отсутствует в типе: проверьте `input`, расширение `.svg`, glob-исключения и необходимость `**/*.svg` для вложенных папок.
|
||||
- Конфликт имени: два разных SVG имеют одинаковый basename; переименуйте один файл.
|
||||
- `Refusing to overwrite a user file`: в корне sprite-модуля находится пользовательский `.gitignore`, который генератор не может заменить.
|
||||
- Иконка не меняет цвет: используйте `<svg><use>` или generated-компонент и проверьте `replaceColors`.
|
||||
- Webpack выдаёт неверный URL: проверьте Asset Modules, `output.publicPath` и SVG loaders.
|
||||
- Static sprite возвращает 404: проверьте post-generation copy или server alias и не передавайте filesystem `spritePath` в HTML.
|
||||
- Viewer не видит спрайт: для bundler modes проверьте путь к `.svg-sprite/svg-sprite.manifest.js`; для bare `standalone` — URL опубликованных `svg-sprite.manifest.json` и `sprite.svg`. Выполните генерацию до запуска приложения.
|
||||
- Build и mode не совпадают: используйте target, соответствующий фактическому сборщику.
|
||||
|
||||
Для собственного orchestration и низкоуровневой компиляции смотрите [Программный API](programmatic-api.md).
|
||||
Reference in New Issue
Block a user