mirror of
https://github.com/gromlab-ru/svg-sprites.git
synced 2026-07-22 04:40:17 +03:00
sync
This commit is contained in:
29
docs/ru/README.md
Normal file
29
docs/ru/README.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# Документация
|
||||
|
||||
Для настройки выберите guide одного exact mode. Каждый guide является
|
||||
самостоятельным документом и без изменений используется в AI skills.
|
||||
|
||||
## Гайды быстрого старта
|
||||
|
||||
| Проект | 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) |
|
||||
| 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) |
|
||||
|
||||
Все guides используют один порядок:
|
||||
|
||||
1. Генерация спрайта через `npx` без добавления package в проект.
|
||||
2. Необязательное подключение Viewer для дебага и превью.
|
||||
3. Необязательная типизация конфига через package или локальный copy-paste type.
|
||||
|
||||
## Справочники
|
||||
|
||||
- [Технический справочник](reference/technical.md)
|
||||
- [Программный API](reference/programmatic-api.md)
|
||||
11
docs/ru/guides/README.md
Normal file
11
docs/ru/guides/README.md
Normal file
@@ -0,0 +1,11 @@
|
||||
# Гайды быстрого старта
|
||||
|
||||
- `standalone`: [bare standalone](standalone.md)
|
||||
- `standalone@vite`: [standalone с Vite](standalone-vite.md)
|
||||
- `standalone@webpack`: [standalone с Webpack](standalone-webpack.md)
|
||||
- `react@vite`: [React с Vite](react-vite.md)
|
||||
- `react@webpack`: [React с Webpack](react-webpack.md)
|
||||
- `next@app/turbopack`: [App Router с Turbopack](next-app-turbopack.md)
|
||||
- `next@app/webpack`: [App Router с Webpack](next-app-webpack.md)
|
||||
- `next@pages/turbopack`: [Pages Router с Turbopack](next-pages-turbopack.md)
|
||||
- `next@pages/webpack`: [Pages Router с Webpack](next-pages-webpack.md)
|
||||
153
docs/ru/guides/next-app-turbopack.md
Normal file
153
docs/ru/guides/next-app-turbopack.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# Next.js App Router с Turbopack
|
||||
|
||||
Это автономный quick start для exact mode key `next@app/turbopack`: generated `IconsIcon` совместим с Server Components и asset pipeline Turbopack.
|
||||
|
||||
## 1. Генерация спрайта
|
||||
|
||||
Главное преимущество: генератор не нужно устанавливать и добавлять в `package.json`. `npx` временно скачивает CLI, а generated production runtime не импортирует `@gromlab/svg-sprites`.
|
||||
|
||||
```text
|
||||
src/sprite/
|
||||
├── icons/
|
||||
│ ├── check.svg
|
||||
│ └── warning.svg
|
||||
├── index.ts
|
||||
└── svg-sprite.config.ts
|
||||
```
|
||||
|
||||
Минимальный plain config:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
mode: 'next@app/turbopack',
|
||||
name: 'icons',
|
||||
}
|
||||
```
|
||||
|
||||
Если `input` не указан, SVG читаются из `./icons` относительно конфига. Конфиг может быть `.ts`, `.js` с `default export` или `.json`.
|
||||
|
||||
```bash
|
||||
npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/sprite/svg-sprite.config.ts
|
||||
```
|
||||
|
||||
В CI зафиксируйте точную версию, например `@gromlab/svg-sprites@1.1.5`. Mode и команды Next должны указывать один bundler:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/sprite/svg-sprite.config.ts",
|
||||
"dev": "npm run sprites && next dev --turbopack",
|
||||
"build": "npm run sprites && next build --turbopack",
|
||||
"start": "next start",
|
||||
"typecheck": "npm run sprites && tsc --noEmit"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Не добавляйте одновременно `predev`/`prebuild` и явный `npm run sprites`. Generated `.svg-sprite` не коммитится. Generated локальный `.gitignore`, который исключает этот каталог, нужно добавить в Git один раз. Его `.d.ts` self-contained и не импортируют generator package.
|
||||
|
||||
```ts
|
||||
// src/sprite/index.ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Generated icon не содержит `'use client'`, поэтому его можно импортировать прямо в Server Component:
|
||||
|
||||
```tsx
|
||||
// app/page.tsx
|
||||
import { IconsIcon, iconsIconNames } from '../src/sprite'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<main>
|
||||
<IconsIcon
|
||||
icon="check"
|
||||
width={24}
|
||||
height={24}
|
||||
aria-label="Готово"
|
||||
style={{ '--icon-color-1': '#16a34a' }}
|
||||
/>
|
||||
<span>{iconsIconNames.length} иконок</span>
|
||||
</main>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Turbopack обрабатывает generated `new URL('../sprite.svg', import.meta.url).href` и выпускает внешний hashed asset. Не добавляйте Client Component boundary только ради `IconsIcon`.
|
||||
|
||||
## 2. Дебаг и превью
|
||||
|
||||
Viewer необязателен и нужен только для debug/preview:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Viewer интерактивен, поэтому создайте для него отдельный Client Component:
|
||||
|
||||
```tsx
|
||||
// app/icons-debug/sprite-viewer.tsx
|
||||
'use client'
|
||||
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('../../src/sprite/.svg-sprite/svg-sprite.manifest.js'),
|
||||
] as const
|
||||
|
||||
export function AppSpriteViewer() {
|
||||
return <SpriteViewer sources={sources} title="Иконки проекта" />
|
||||
}
|
||||
```
|
||||
|
||||
Server page импортирует только эту boundary:
|
||||
|
||||
```tsx
|
||||
// app/icons-debug/page.tsx
|
||||
import { AppSpriteViewer } from './sprite-viewer'
|
||||
|
||||
export default function IconsDebugPage() {
|
||||
return <AppSpriteViewer />
|
||||
}
|
||||
```
|
||||
|
||||
Viewer не входит в production icon runtime и не нужен обычным страницам с `IconsIcon`.
|
||||
|
||||
## 3. Типизация конфига
|
||||
|
||||
После локальной установки package используйте helper:
|
||||
|
||||
```ts
|
||||
import { defineSpriteConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default defineSpriteConfig({
|
||||
mode: 'next@app/turbopack',
|
||||
name: 'icons',
|
||||
})
|
||||
```
|
||||
|
||||
Возможен и type-only import `SpriteConfig` с `satisfies SpriteConfig`.
|
||||
|
||||
Без package добавьте локальный type в config:
|
||||
|
||||
```ts
|
||||
type LocalSpriteConfig = {
|
||||
mode: 'next@app/turbopack'
|
||||
name?: string
|
||||
description?: string
|
||||
input?: string | string[]
|
||||
transform?: {
|
||||
removeSize?: boolean
|
||||
replaceColors?: boolean
|
||||
addTransition?: boolean
|
||||
}
|
||||
generatedNotice?: boolean
|
||||
}
|
||||
|
||||
export default {
|
||||
mode: 'next@app/turbopack',
|
||||
name: 'icons',
|
||||
} satisfies LocalSpriteConfig
|
||||
```
|
||||
|
||||
Exact literal защищает от смешивания App Router и других bundler contracts.
|
||||
151
docs/ru/guides/next-app-webpack.md
Normal file
151
docs/ru/guides/next-app-webpack.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# Next.js App Router с Webpack
|
||||
|
||||
Это автономный quick start для exact mode key `next@app/webpack`: generated `IconsIcon` совместим с Server Components и Webpack pipeline Next.js.
|
||||
|
||||
## 1. Генерация спрайта
|
||||
|
||||
Главное преимущество: генератор не нужно устанавливать и добавлять в `package.json`. `npx` временно скачивает CLI, а generated production runtime не импортирует `@gromlab/svg-sprites`.
|
||||
|
||||
```text
|
||||
src/sprite/
|
||||
├── icons/
|
||||
│ ├── check.svg
|
||||
│ └── warning.svg
|
||||
├── index.ts
|
||||
└── svg-sprite.config.ts
|
||||
```
|
||||
|
||||
Минимальный plain config:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
mode: 'next@app/webpack',
|
||||
name: 'icons',
|
||||
}
|
||||
```
|
||||
|
||||
Если `input` не указан, SVG читаются из `./icons` относительно конфига. Также поддерживаются `.js` с `default export` и `.json`.
|
||||
|
||||
```bash
|
||||
npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/sprite/svg-sprite.config.ts
|
||||
```
|
||||
|
||||
В CI замените `latest` точной версией, например `@gromlab/svg-sprites@1.1.5`. Exact Next commands для этого mode:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/sprite/svg-sprite.config.ts",
|
||||
"dev": "npm run sprites && next dev --webpack",
|
||||
"build": "npm run sprites && next build --webpack",
|
||||
"start": "next start",
|
||||
"typecheck": "npm run sprites && tsc --noEmit"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Не сочетайте явный `npm run sprites` с `predev` или `prebuild`. `.svg-sprite` generated и не коммитится. Generated локальный `.gitignore`, который исключает этот каталог, нужно добавить в Git один раз. Generated declarations self-contained и не зависят от `@gromlab/svg-sprites`.
|
||||
|
||||
```ts
|
||||
// src/sprite/index.ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Production usage в Server Component:
|
||||
|
||||
```tsx
|
||||
// app/page.tsx
|
||||
import { IconsIcon, iconsIconNames } from '../src/sprite'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<main>
|
||||
<IconsIcon
|
||||
icon="check"
|
||||
width={24}
|
||||
height={24}
|
||||
aria-label="Готово"
|
||||
style={{ '--icon-color-1': '#16a34a' }}
|
||||
/>
|
||||
<span>{iconsIconNames.length} иконок</span>
|
||||
</main>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Generated component не содержит `'use client'`. Next Webpack обрабатывает `new URL('../sprite.svg', import.meta.url).href` и публикует отдельный SVG asset; не переписывайте этот URL и не переносите sprite в `public` вручную.
|
||||
|
||||
## 2. Дебаг и превью
|
||||
|
||||
Viewer необязателен. Для debug/preview установите package:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
App Router требует отдельную Client Component boundary для Viewer:
|
||||
|
||||
```tsx
|
||||
// app/icons-debug/sprite-viewer.tsx
|
||||
'use client'
|
||||
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('../../src/sprite/.svg-sprite/svg-sprite.manifest.js'),
|
||||
] as const
|
||||
|
||||
export function AppSpriteViewer() {
|
||||
return <SpriteViewer sources={sources} title="Иконки проекта" />
|
||||
}
|
||||
```
|
||||
|
||||
```tsx
|
||||
// app/icons-debug/page.tsx
|
||||
import { AppSpriteViewer } from './sprite-viewer'
|
||||
|
||||
export default function IconsDebugPage() {
|
||||
return <AppSpriteViewer />
|
||||
}
|
||||
```
|
||||
|
||||
Статический loader позволяет Webpack связать manifest и emitted SVG. Viewer не входит в production runtime `IconsIcon`.
|
||||
|
||||
## 3. Типизация конфига
|
||||
|
||||
При локально установленном package используйте helper:
|
||||
|
||||
```ts
|
||||
import { defineSpriteConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default defineSpriteConfig({
|
||||
mode: 'next@app/webpack',
|
||||
name: 'icons',
|
||||
})
|
||||
```
|
||||
|
||||
Другой package-вариант: type-only import `SpriteConfig` и `satisfies SpriteConfig`.
|
||||
|
||||
Без package вставьте локальный type прямо в config:
|
||||
|
||||
```ts
|
||||
type LocalSpriteConfig = {
|
||||
mode: 'next@app/webpack'
|
||||
name?: string
|
||||
description?: string
|
||||
input?: string | string[]
|
||||
transform?: {
|
||||
removeSize?: boolean
|
||||
replaceColors?: boolean
|
||||
addTransition?: boolean
|
||||
}
|
||||
generatedNotice?: boolean
|
||||
}
|
||||
|
||||
export default {
|
||||
mode: 'next@app/webpack',
|
||||
name: 'icons',
|
||||
} satisfies LocalSpriteConfig
|
||||
```
|
||||
|
||||
Локальный exact literal исключает случайную генерацию Turbopack или Pages Router output.
|
||||
140
docs/ru/guides/next-pages-turbopack.md
Normal file
140
docs/ru/guides/next-pages-turbopack.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# Next.js Pages Router с Turbopack
|
||||
|
||||
Это автономный quick start для exact mode key `next@pages/turbopack`: generated `IconsIcon` работает при SSR, SSG и клиентских переходах Pages Router.
|
||||
|
||||
## 1. Генерация спрайта
|
||||
|
||||
Главное преимущество: генератор не нужно устанавливать и добавлять в `package.json`. `npx` временно скачивает CLI, а generated production runtime не импортирует `@gromlab/svg-sprites`.
|
||||
|
||||
```text
|
||||
src/sprite/
|
||||
├── icons/
|
||||
│ ├── check.svg
|
||||
│ └── warning.svg
|
||||
├── index.ts
|
||||
└── svg-sprite.config.ts
|
||||
```
|
||||
|
||||
Минимальный plain config:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
mode: 'next@pages/turbopack',
|
||||
name: 'icons',
|
||||
}
|
||||
```
|
||||
|
||||
Если `input` не указан, SVG читаются из `./icons` относительно конфига. Конфиг также может быть `.js` с `default export` или `.json`.
|
||||
|
||||
```bash
|
||||
npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/sprite/svg-sprite.config.ts
|
||||
```
|
||||
|
||||
Для CI зафиксируйте точную версию, например `@gromlab/svg-sprites@1.1.5`. Exact commands должны сохранять Turbopack и для dev, и для production build:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/sprite/svg-sprite.config.ts",
|
||||
"dev": "npm run sprites && next dev --turbopack",
|
||||
"build": "npm run sprites && next build --turbopack",
|
||||
"start": "next start",
|
||||
"typecheck": "npm run sprites && tsc --noEmit"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Не добавляйте `predev`/`prebuild`, если scripts уже явно вызывают `npm run sprites`. Generated `.svg-sprite` не коммитится. Generated локальный `.gitignore`, который исключает этот каталог, нужно добавить в Git один раз. Generated `.d.ts` self-contained и не импортируют generator package.
|
||||
|
||||
```ts
|
||||
// src/sprite/index.ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Production usage на обычной page:
|
||||
|
||||
```tsx
|
||||
// pages/index.tsx
|
||||
import { IconsIcon, iconsIconNames } from '../src/sprite'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<main>
|
||||
<IconsIcon
|
||||
icon="check"
|
||||
width={24}
|
||||
height={24}
|
||||
aria-label="Готово"
|
||||
style={{ '--icon-color-1': '#16a34a' }}
|
||||
/>
|
||||
<span>{iconsIconNames.length} иконок</span>
|
||||
</main>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Компонент одинаково работает с `getServerSideProps`, `getStaticProps` и client navigation. Turbopack разрешает generated `new URL('../sprite.svg', import.meta.url).href` в отдельный hashed asset.
|
||||
|
||||
## 2. Дебаг и превью
|
||||
|
||||
Viewer необязателен и нужен только для debug/preview:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
В Pages Router Viewer можно использовать прямо в page, без отдельной App Router Client Component boundary:
|
||||
|
||||
```tsx
|
||||
// pages/icons-debug.tsx
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('../src/sprite/.svg-sprite/svg-sprite.manifest.js'),
|
||||
] as const
|
||||
|
||||
export default function IconsDebugPage() {
|
||||
return <SpriteViewer sources={sources} title="Иконки проекта" />
|
||||
}
|
||||
```
|
||||
|
||||
Оставляйте эту page только во внутреннем debug-разделе. Viewer не входит в production icon runtime `IconsIcon`.
|
||||
|
||||
## 3. Типизация конфига
|
||||
|
||||
Если package установлен локально, используйте helper:
|
||||
|
||||
```ts
|
||||
import { defineSpriteConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default defineSpriteConfig({
|
||||
mode: 'next@pages/turbopack',
|
||||
name: 'icons',
|
||||
})
|
||||
```
|
||||
|
||||
Альтернатива: type-only import `SpriteConfig` и объект `satisfies SpriteConfig`.
|
||||
|
||||
Без package добавьте copy-paste type в config:
|
||||
|
||||
```ts
|
||||
type LocalSpriteConfig = {
|
||||
mode: 'next@pages/turbopack'
|
||||
name?: string
|
||||
description?: string
|
||||
input?: string | string[]
|
||||
transform?: {
|
||||
removeSize?: boolean
|
||||
replaceColors?: boolean
|
||||
addTransition?: boolean
|
||||
}
|
||||
generatedNotice?: boolean
|
||||
}
|
||||
|
||||
export default {
|
||||
mode: 'next@pages/turbopack',
|
||||
name: 'icons',
|
||||
} satisfies LocalSpriteConfig
|
||||
```
|
||||
|
||||
Exact literal не позволяет незаметно смешать Pages Router с App Router или Webpack output.
|
||||
140
docs/ru/guides/next-pages-webpack.md
Normal file
140
docs/ru/guides/next-pages-webpack.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# Next.js Pages Router с Webpack
|
||||
|
||||
Это автономный quick start для exact mode key `next@pages/webpack`: generated `IconsIcon` работает в Pages Router и публикует SVG через Webpack pipeline Next.js.
|
||||
|
||||
## 1. Генерация спрайта
|
||||
|
||||
Главное преимущество: генератор не нужно устанавливать и добавлять в `package.json`. `npx` временно скачивает CLI, а generated production runtime не импортирует `@gromlab/svg-sprites`.
|
||||
|
||||
```text
|
||||
src/sprite/
|
||||
├── icons/
|
||||
│ ├── check.svg
|
||||
│ └── warning.svg
|
||||
├── index.ts
|
||||
└── svg-sprite.config.ts
|
||||
```
|
||||
|
||||
Минимальный plain config:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
mode: 'next@pages/webpack',
|
||||
name: 'icons',
|
||||
}
|
||||
```
|
||||
|
||||
Если `input` не указан, SVG читаются из `./icons` относительно конфига. Поддерживаются `.ts`, `.js` с `default export` и `.json` configs.
|
||||
|
||||
```bash
|
||||
npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/sprite/svg-sprite.config.ts
|
||||
```
|
||||
|
||||
В CI замените `latest` на точную проверенную версию, например `@gromlab/svg-sprites@1.1.5`. Exact Next commands для Webpack:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/sprite/svg-sprite.config.ts",
|
||||
"dev": "npm run sprites && next dev --webpack",
|
||||
"build": "npm run sprites && next build --webpack",
|
||||
"start": "next start",
|
||||
"typecheck": "npm run sprites && tsc --noEmit"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Не дублируйте эти вызовы через `predev`, `prebuild` или `pretypecheck`. `.svg-sprite` generated и не коммитится. Generated локальный `.gitignore`, который исключает этот каталог, нужно добавить в Git один раз. Generated declarations self-contained и не требуют `@gromlab/svg-sprites`.
|
||||
|
||||
```ts
|
||||
// src/sprite/index.ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Production usage:
|
||||
|
||||
```tsx
|
||||
// pages/index.tsx
|
||||
import { IconsIcon, iconsIconNames } from '../src/sprite'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<main>
|
||||
<IconsIcon
|
||||
icon="check"
|
||||
width={24}
|
||||
height={24}
|
||||
aria-label="Готово"
|
||||
style={{ '--icon-color-1': '#16a34a' }}
|
||||
/>
|
||||
<span>{iconsIconNames.length} иконок</span>
|
||||
</main>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Компонент поддерживает SSR, SSG и клиентские переходы. Next Webpack преобразует generated `new URL('../sprite.svg', import.meta.url).href` во внешний hashed asset; не конструируйте URL спрайта вручную.
|
||||
|
||||
## 2. Дебаг и превью
|
||||
|
||||
Viewer необязателен. Устанавливайте package только для debug/preview:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Pages Router позволяет разместить Viewer непосредственно в page без отдельной App Router boundary:
|
||||
|
||||
```tsx
|
||||
// pages/icons-debug.tsx
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('../src/sprite/.svg-sprite/svg-sprite.manifest.js'),
|
||||
] as const
|
||||
|
||||
export default function IconsDebugPage() {
|
||||
return <SpriteViewer sources={sources} title="Иконки проекта" />
|
||||
}
|
||||
```
|
||||
|
||||
Статический loader даёт Webpack точный manifest module и связанный SVG asset. Не импортируйте Viewer из production pages, если preview там не нужен; runtime `IconsIcon` от него независим.
|
||||
|
||||
## 3. Типизация конфига
|
||||
|
||||
После локальной установки package доступен helper:
|
||||
|
||||
```ts
|
||||
import { defineSpriteConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default defineSpriteConfig({
|
||||
mode: 'next@pages/webpack',
|
||||
name: 'icons',
|
||||
})
|
||||
```
|
||||
|
||||
Также можно применить `satisfies SpriteConfig` с type-only импортом `SpriteConfig`.
|
||||
|
||||
Без package вставьте локальный type прямо в config:
|
||||
|
||||
```ts
|
||||
type LocalSpriteConfig = {
|
||||
mode: 'next@pages/webpack'
|
||||
name?: string
|
||||
description?: string
|
||||
input?: string | string[]
|
||||
transform?: {
|
||||
removeSize?: boolean
|
||||
replaceColors?: boolean
|
||||
addTransition?: boolean
|
||||
}
|
||||
generatedNotice?: boolean
|
||||
}
|
||||
|
||||
export default {
|
||||
mode: 'next@pages/webpack',
|
||||
name: 'icons',
|
||||
} satisfies LocalSpriteConfig
|
||||
```
|
||||
|
||||
Такой exact literal выявляет ошибочный выбор App Router или Turbopack ещё при проверке config.
|
||||
141
docs/ru/guides/react-vite.md
Normal file
141
docs/ru/guides/react-vite.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# React-компонент для Vite
|
||||
|
||||
Это автономный quick start для exact mode key `react@vite`: генератор создаёт типизированный `IconsIcon`, а Vite публикует отдельный SVG asset.
|
||||
|
||||
## 1. Генерация спрайта
|
||||
|
||||
Главное преимущество: генератор не нужно устанавливать и добавлять в `package.json`. `npx` временно скачивает CLI, а generated production runtime не импортирует `@gromlab/svg-sprites`.
|
||||
|
||||
```text
|
||||
src/sprite/
|
||||
├── icons/
|
||||
│ ├── check.svg
|
||||
│ └── warning.svg
|
||||
├── index.ts
|
||||
└── svg-sprite.config.ts
|
||||
```
|
||||
|
||||
Минимальный plain config:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
mode: 'react@vite',
|
||||
name: 'icons',
|
||||
}
|
||||
```
|
||||
|
||||
Если `input` не указан, SVG читаются из `./icons` относительно конфига. Вместо `.ts` можно использовать `.js` с `default export` или `.json`.
|
||||
|
||||
```bash
|
||||
npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/sprite/svg-sprite.config.ts
|
||||
```
|
||||
|
||||
В CI замените `latest` на точную версию, например `@gromlab/svg-sprites@1.1.5`. Exact Vite commands:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/sprite/svg-sprite.config.ts",
|
||||
"dev": "npm run sprites && vite",
|
||||
"build": "npm run sprites && tsc --noEmit && vite build",
|
||||
"typecheck": "npm run sprites && tsc --noEmit"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Не добавляйте `predev`, `prebuild` или `pretypecheck`, если соответствующие scripts уже явно запускают `npm run sprites`. Generated `.svg-sprite` не коммитится. Generated локальный `.gitignore`, который исключает этот каталог, нужно добавить в Git один раз. Generated declarations self-contained: они описывают компонент и manifest без импорта `@gromlab/svg-sprites`.
|
||||
|
||||
Пользовательский barrel возвращает generated API:
|
||||
|
||||
```ts
|
||||
// src/sprite/index.ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Production usage:
|
||||
|
||||
```tsx
|
||||
import { IconsIcon, iconsIconNames } from './sprite'
|
||||
|
||||
export function SaveButton() {
|
||||
return (
|
||||
<button type="button">
|
||||
<IconsIcon
|
||||
icon="check"
|
||||
width={24}
|
||||
height={24}
|
||||
aria-hidden="true"
|
||||
style={{ '--icon-color-1': '#16a34a' }}
|
||||
/>
|
||||
Сохранить
|
||||
</button>
|
||||
)
|
||||
}
|
||||
|
||||
console.log(iconsIconNames)
|
||||
```
|
||||
|
||||
Prop `icon` является union имён исходных файлов. Vite автоматически обрабатывает generated CSS Module и импорт `sprite.svg?no-inline`; query запрещает inline и заставляет Vite выпустить отдельный hashed SVG asset. Если TypeScript не знает Vite asset imports, добавьте `/// <reference types="vite/client" />` в `src/vite-env.d.ts`.
|
||||
|
||||
## 2. Дебаг и превью
|
||||
|
||||
Viewer необязателен и нужен только для debug/preview. Установите package отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Используйте React bridge со статическим массивом loaders:
|
||||
|
||||
```tsx
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('./sprite/.svg-sprite/svg-sprite.manifest.js'),
|
||||
] as const
|
||||
|
||||
export function IconsDebugPage() {
|
||||
return <SpriteViewer sources={sources} title="Иконки проекта" />
|
||||
}
|
||||
```
|
||||
|
||||
Строковый путь в `import()` должен указывать на generated JS manifest. Держите страницу за debug-маршрутом; `SpriteViewer` не входит в production runtime `IconsIcon`.
|
||||
|
||||
## 3. Типизация конфига
|
||||
|
||||
Если package установлен локально, используйте helper:
|
||||
|
||||
```ts
|
||||
import { defineSpriteConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default defineSpriteConfig({
|
||||
mode: 'react@vite',
|
||||
name: 'icons',
|
||||
})
|
||||
```
|
||||
|
||||
Также можно импортировать `SpriteConfig` только как type и написать объект `satisfies SpriteConfig`.
|
||||
|
||||
Без package добавьте локальный type прямо в config:
|
||||
|
||||
```ts
|
||||
type LocalSpriteConfig = {
|
||||
mode: 'react@vite'
|
||||
name?: string
|
||||
description?: string
|
||||
input?: string | string[]
|
||||
transform?: {
|
||||
removeSize?: boolean
|
||||
replaceColors?: boolean
|
||||
addTransition?: boolean
|
||||
}
|
||||
generatedNotice?: boolean
|
||||
}
|
||||
|
||||
export default {
|
||||
mode: 'react@vite',
|
||||
name: 'icons',
|
||||
} satisfies LocalSpriteConfig
|
||||
```
|
||||
|
||||
Локальный type проверяет только этот exact mode и не создаёт runtime-зависимость.
|
||||
141
docs/ru/guides/react-webpack.md
Normal file
141
docs/ru/guides/react-webpack.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# React-компонент для Webpack 5
|
||||
|
||||
Это автономный quick start для exact mode key `react@webpack`: generated `IconsIcon` использует Webpack 5 Asset Modules и CSS Modules.
|
||||
|
||||
## 1. Генерация спрайта
|
||||
|
||||
Главное преимущество: генератор не нужно устанавливать и добавлять в `package.json`. `npx` временно скачивает CLI, а generated production runtime не импортирует `@gromlab/svg-sprites`.
|
||||
|
||||
```text
|
||||
src/sprite/
|
||||
├── icons/
|
||||
│ ├── check.svg
|
||||
│ └── warning.svg
|
||||
├── index.ts
|
||||
└── svg-sprite.config.ts
|
||||
```
|
||||
|
||||
Минимальный plain config:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
mode: 'react@webpack',
|
||||
name: 'icons',
|
||||
}
|
||||
```
|
||||
|
||||
Если `input` не указан, SVG читаются из `./icons` относительно конфига. Поддерживаются `.ts`, `.js` с `default export` и `.json` configs.
|
||||
|
||||
```bash
|
||||
npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/sprite/svg-sprite.config.ts
|
||||
```
|
||||
|
||||
В CI замените `latest` на точную версию, например `@gromlab/svg-sprites@1.1.5`. Exact Webpack commands:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/sprite/svg-sprite.config.ts",
|
||||
"dev": "npm run sprites && webpack serve --mode development",
|
||||
"build": "npm run sprites && webpack --mode production",
|
||||
"typecheck": "npm run sprites && tsc --noEmit"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Не сочетайте эти явные вызовы с `predev`/`prebuild`: иначе генерация задублируется. `.svg-sprite` не коммитится. Generated локальный `.gitignore`, который исключает этот каталог, нужно добавить в Git один раз. Generated `.d.ts` self-contained и не импортируют generator package.
|
||||
|
||||
```ts
|
||||
// src/sprite/index.ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Production usage:
|
||||
|
||||
```tsx
|
||||
import { IconsIcon, iconsIconNames } from './sprite'
|
||||
|
||||
export function SaveButton() {
|
||||
return (
|
||||
<button type="button">
|
||||
<IconsIcon
|
||||
icon="check"
|
||||
width={24}
|
||||
height={24}
|
||||
aria-hidden="true"
|
||||
style={{ '--icon-color-1': '#16a34a' }}
|
||||
/>
|
||||
Сохранить
|
||||
</button>
|
||||
)
|
||||
}
|
||||
|
||||
console.log(iconsIconNames)
|
||||
```
|
||||
|
||||
Generated component получает URL через `new URL('../sprite.svg', import.meta.url).href`. Webpack 5 должен обработать SVG как Asset Module. Исключите generated `sprite.svg` из `@svgr/webpack`, inline/raw loaders и других общих SVG rules либо задайте для него `type: 'asset/resource'`.
|
||||
|
||||
Компонент импортирует `react-component.module.css`. Webpack config должен обрабатывать `*.module.css` через `css-loader` с CSS Modules и `style-loader` или `MiniCssExtractPlugin`. Для TypeScript при необходимости добавьте декларацию `declare module '*.module.css'`.
|
||||
|
||||
## 2. Дебаг и превью
|
||||
|
||||
Viewer необязателен. Устанавливайте package только для debug/preview:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Webpack не использует `import.meta.glob`; передайте статический loader:
|
||||
|
||||
```tsx
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('./sprite/.svg-sprite/svg-sprite.manifest.js'),
|
||||
] as const
|
||||
|
||||
export function IconsDebugPage() {
|
||||
return <SpriteViewer sources={sources} title="Иконки проекта" />
|
||||
}
|
||||
```
|
||||
|
||||
Webpack создаст chunk manifest и разрешит его SVG через тот же Asset Modules pipeline. Viewer держите только в debug route; production `IconsIcon` от него не зависит.
|
||||
|
||||
## 3. Типизация конфига
|
||||
|
||||
С локально установленным package доступен helper:
|
||||
|
||||
```ts
|
||||
import { defineSpriteConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default defineSpriteConfig({
|
||||
mode: 'react@webpack',
|
||||
name: 'icons',
|
||||
})
|
||||
```
|
||||
|
||||
Эквивалентная проверка: type-only import `SpriteConfig` и `satisfies SpriteConfig`.
|
||||
|
||||
Без package используйте copy-paste type в config:
|
||||
|
||||
```ts
|
||||
type LocalSpriteConfig = {
|
||||
mode: 'react@webpack'
|
||||
name?: string
|
||||
description?: string
|
||||
input?: string | string[]
|
||||
transform?: {
|
||||
removeSize?: boolean
|
||||
replaceColors?: boolean
|
||||
addTransition?: boolean
|
||||
}
|
||||
generatedNotice?: boolean
|
||||
}
|
||||
|
||||
export default {
|
||||
mode: 'react@webpack',
|
||||
name: 'icons',
|
||||
} satisfies LocalSpriteConfig
|
||||
```
|
||||
|
||||
Локальный literal не разрешит случайно выбрать Vite или Next mode.
|
||||
151
docs/ru/guides/standalone-vite.md
Normal file
151
docs/ru/guides/standalone-vite.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# Нативный icon Web Component с Vite
|
||||
|
||||
Это автономный quick start для exact mode key `standalone@vite`: generated facade регистрирует `<icons-icon>` и отдаёт SVG в asset pipeline Vite.
|
||||
|
||||
## 1. Генерация спрайта
|
||||
|
||||
Главное преимущество: генератор не нужно устанавливать и добавлять в `package.json`. `npx` временно скачивает CLI, а generated production runtime не импортирует `@gromlab/svg-sprites`.
|
||||
|
||||
Рекомендуемая структура держит конфиг и иконки рядом:
|
||||
|
||||
```text
|
||||
src/sprite/
|
||||
├── icons/
|
||||
│ ├── check.svg
|
||||
│ └── warning.svg
|
||||
├── index.ts
|
||||
└── svg-sprite.config.ts
|
||||
```
|
||||
|
||||
Минимальный plain config:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
mode: 'standalone@vite',
|
||||
name: 'icons',
|
||||
}
|
||||
```
|
||||
|
||||
Если `input` не указан, SVG читаются из `./icons` относительно конфига. Конфиг также может быть `.js` с `default export` или `.json`.
|
||||
|
||||
```bash
|
||||
npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/sprite/svg-sprite.config.ts
|
||||
```
|
||||
|
||||
В CI замените `latest` на точную версию, например `@gromlab/svg-sprites@1.1.5`. Exact dev/build commands для Vite:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/sprite/svg-sprite.config.ts",
|
||||
"dev": "npm run sprites && vite",
|
||||
"build": "npm run sprites && vite build",
|
||||
"typecheck": "npm run sprites && tsc --noEmit"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Не добавляйте одновременно `predev`/`prebuild` и явный `npm run sprites` в этих scripts. `.svg-sprite` является generated-каталогом и не коммитится. Generated локальный `.gitignore`, который исключает этот каталог, нужно добавить в Git один раз. Generated `.d.ts` self-contained и не импортируют `@gromlab/svg-sprites`.
|
||||
|
||||
Верните facade через пользовательский barrel:
|
||||
|
||||
```ts
|
||||
// src/sprite/index.ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Production entry регистрирует native Web Component:
|
||||
|
||||
```ts
|
||||
import { defineIconsIconElement, iconsIconNames } from './sprite'
|
||||
|
||||
defineIconsIconElement()
|
||||
|
||||
document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
|
||||
<icons-icon icon="check" role="img" aria-label="Готово"></icons-icon>
|
||||
`
|
||||
|
||||
console.log(iconsIconNames)
|
||||
```
|
||||
|
||||
Generated facade импортирует `sprite.svg?no-inline`: Vite автоматически выпускает отдельный hashed SVG asset и не превращает его в data URL. TypeScript-проекту при необходимости добавьте стандартные Vite types:
|
||||
|
||||
```ts
|
||||
/// <reference types="vite/client" />
|
||||
```
|
||||
|
||||
Размер по умолчанию равен `1em`, поэтому компонент удобно масштабировать через `font-size`. Цвет задаётся через `color` и generated custom properties:
|
||||
|
||||
```css
|
||||
icons-icon {
|
||||
font-size: 24px;
|
||||
color: #334155;
|
||||
--icon-color-2: #f59e0b;
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Дебаг и превью
|
||||
|
||||
Viewer необязателен и нужен только для debug/preview. Установите его отдельно:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Зарегистрируйте Viewer и передайте generated JS manifest через свойство `sources`:
|
||||
|
||||
```ts
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
import type { SpriteViewerElement } from '@gromlab/svg-sprites/viewer'
|
||||
import spriteManifest from './sprite/.svg-sprite/svg-sprite.manifest.js'
|
||||
|
||||
document.querySelector<HTMLDivElement>('#app')!.insertAdjacentHTML(
|
||||
'beforeend',
|
||||
'<gromlab-sprite-viewer></gromlab-sprite-viewer>',
|
||||
)
|
||||
|
||||
const viewer = document.querySelector<SpriteViewerElement>('gromlab-sprite-viewer')!
|
||||
viewer.viewerTitle = 'Иконки проекта'
|
||||
viewer.sources = [spriteManifest]
|
||||
```
|
||||
|
||||
Расположите этот код только в debug entry или внутреннем маршруте. Viewer не входит в production runtime `<icons-icon>`.
|
||||
|
||||
## 3. Типизация конфига
|
||||
|
||||
При локально установленном package используйте helper:
|
||||
|
||||
```ts
|
||||
import { defineSpriteConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default defineSpriteConfig({
|
||||
mode: 'standalone@vite',
|
||||
name: 'icons',
|
||||
})
|
||||
```
|
||||
|
||||
Альтернатива с package: `import type { SpriteConfig }` и объект `satisfies SpriteConfig`.
|
||||
|
||||
Без package скопируйте локальный type прямо в config:
|
||||
|
||||
```ts
|
||||
type LocalSpriteConfig = {
|
||||
mode: 'standalone@vite'
|
||||
name?: string
|
||||
description?: string
|
||||
input?: string | string[]
|
||||
transform?: {
|
||||
removeSize?: boolean
|
||||
replaceColors?: boolean
|
||||
addTransition?: boolean
|
||||
}
|
||||
generatedNotice?: boolean
|
||||
}
|
||||
|
||||
export default {
|
||||
mode: 'standalone@vite',
|
||||
name: 'icons',
|
||||
} satisfies LocalSpriteConfig
|
||||
```
|
||||
|
||||
Локальный type ограничивает `mode` одним exact literal и ничего не загружает во время генерации.
|
||||
145
docs/ru/guides/standalone-webpack.md
Normal file
145
docs/ru/guides/standalone-webpack.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# Нативный icon Web Component с Webpack 5
|
||||
|
||||
Это автономный quick start для exact mode key `standalone@webpack`: generated facade предоставляет `<icons-icon>`, а Webpack 5 публикует SVG через Asset Modules.
|
||||
|
||||
## 1. Генерация спрайта
|
||||
|
||||
Главное преимущество: генератор не нужно устанавливать и добавлять в `package.json`. `npx` временно скачивает CLI, а generated production runtime не импортирует `@gromlab/svg-sprites`.
|
||||
|
||||
```text
|
||||
src/sprite/
|
||||
├── icons/
|
||||
│ ├── check.svg
|
||||
│ └── warning.svg
|
||||
├── index.ts
|
||||
└── svg-sprite.config.ts
|
||||
```
|
||||
|
||||
Минимальный config рядом с `icons/`:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
mode: 'standalone@webpack',
|
||||
name: 'icons',
|
||||
}
|
||||
```
|
||||
|
||||
Если `input` не указан, SVG читаются из `./icons` относительно конфига. Поддерживаются также `.js` с `default export` и `.json`.
|
||||
|
||||
```bash
|
||||
npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/sprite/svg-sprite.config.ts
|
||||
```
|
||||
|
||||
Для CI закрепите точную версию, например `@gromlab/svg-sprites@1.1.5`. Exact Webpack commands:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "npx --yes --package=@gromlab/svg-sprites@latest svg-sprites src/sprite/svg-sprite.config.ts",
|
||||
"dev": "npm run sprites && webpack serve --mode development",
|
||||
"build": "npm run sprites && webpack --mode production",
|
||||
"typecheck": "npm run sprites && tsc --noEmit"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Не дублируйте запуск через `predev`/`prebuild`, если scripts уже явно вызывают `npm run sprites`. Generated `.svg-sprite` не коммитится. Generated локальный `.gitignore`, который исключает этот каталог, нужно добавить в Git один раз. Его declarations self-contained и не требуют `@gromlab/svg-sprites`.
|
||||
|
||||
```ts
|
||||
// src/sprite/index.ts
|
||||
export * from './.svg-sprite/index.js'
|
||||
```
|
||||
|
||||
Production usage:
|
||||
|
||||
```ts
|
||||
import { defineIconsIconElement, iconsIconNames } from './sprite'
|
||||
|
||||
defineIconsIconElement()
|
||||
|
||||
document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
|
||||
<icons-icon icon="check" role="img" aria-label="Готово"></icons-icon>
|
||||
`
|
||||
|
||||
console.log(iconsIconNames)
|
||||
```
|
||||
|
||||
Generated facade использует `new URL('./sprite.svg', import.meta.url).href`. Webpack 5 Asset Modules выпускают отдельный asset; его итоговый URL учитывает `output.publicPath` и `assetModuleFilename`.
|
||||
|
||||
Если проект использует `@svgr/webpack`, `svg-inline-loader`, `raw-loader` или общий SVG rule, исключите `src/sprite/.svg-sprite/sprite.svg` из этого правила. Generated SVG должен обрабатываться как `asset/resource`, а не как React-компонент или inline source.
|
||||
|
||||
Размер Web Component по умолчанию `1em`; управляйте им и цветами обычным CSS:
|
||||
|
||||
```css
|
||||
icons-icon {
|
||||
font-size: 24px;
|
||||
color: #334155;
|
||||
--icon-color-2: #f59e0b;
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Дебаг и превью
|
||||
|
||||
Viewer необязателен. Для debug/preview установите package как dev dependency:
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
Подключите element entry и generated JS manifest:
|
||||
|
||||
```ts
|
||||
import '@gromlab/svg-sprites/viewer/element'
|
||||
import type { SpriteViewerElement } from '@gromlab/svg-sprites/viewer'
|
||||
import spriteManifest from './sprite/.svg-sprite/svg-sprite.manifest.js'
|
||||
|
||||
document.querySelector<HTMLDivElement>('#app')!.insertAdjacentHTML(
|
||||
'beforeend',
|
||||
'<gromlab-sprite-viewer></gromlab-sprite-viewer>',
|
||||
)
|
||||
|
||||
const viewer = document.querySelector<SpriteViewerElement>('gromlab-sprite-viewer')!
|
||||
viewer.viewerTitle = 'Иконки проекта'
|
||||
viewer.sources = [spriteManifest]
|
||||
```
|
||||
|
||||
Webpack свяжет manifest с тем же emitted SVG asset. Оставляйте Viewer только в debug entry: production `<icons-icon>` от него не зависит.
|
||||
|
||||
## 3. Типизация конфига
|
||||
|
||||
После локальной установки package можно использовать helper:
|
||||
|
||||
```ts
|
||||
import { defineSpriteConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default defineSpriteConfig({
|
||||
mode: 'standalone@webpack',
|
||||
name: 'icons',
|
||||
})
|
||||
```
|
||||
|
||||
Либо импортируйте только `SpriteConfig` как type и примените `satisfies SpriteConfig`.
|
||||
|
||||
Без package добавьте copy-paste type в сам config:
|
||||
|
||||
```ts
|
||||
type LocalSpriteConfig = {
|
||||
mode: 'standalone@webpack'
|
||||
name?: string
|
||||
description?: string
|
||||
input?: string | string[]
|
||||
transform?: {
|
||||
removeSize?: boolean
|
||||
replaceColors?: boolean
|
||||
addTransition?: boolean
|
||||
}
|
||||
generatedNotice?: boolean
|
||||
}
|
||||
|
||||
export default {
|
||||
mode: 'standalone@webpack',
|
||||
name: 'icons',
|
||||
} satisfies LocalSpriteConfig
|
||||
```
|
||||
|
||||
Этот вариант сохраняет проверку exact mode без runtime import и без записи generator package в проект.
|
||||
108
docs/ru/guides/standalone.md
Normal file
108
docs/ru/guides/standalone.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# SVG-спрайт для сайта без сборщика
|
||||
|
||||
Соберите SVG-иконки в один файл и используйте их на HTML-странице.
|
||||
|
||||
## Генерация спрайта
|
||||
|
||||
Устанавливать пакет в проект не нужно.
|
||||
|
||||
В руководстве используется следующая структура проекта:
|
||||
|
||||
```text
|
||||
/
|
||||
├── index.html
|
||||
└── assets/
|
||||
├── app-icons/
|
||||
└── svg-icons/
|
||||
├── check.svg
|
||||
└── warning.svg
|
||||
```
|
||||
|
||||
### 1. Создайте конфиг спрайта
|
||||
|
||||
Выберите папку для спрайта. В этом примере используется `assets/app-icons`. Создайте в ней файл `svg-sprite.config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "standalone",
|
||||
"name": "icons"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Укажите источник иконок
|
||||
|
||||
В `input` можно указать папку, отдельный SVG-файл или glob-шаблон. Для нескольких источников используйте массив с любой комбинацией этих значений:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "standalone",
|
||||
"name": "icons",
|
||||
"input": "../svg-icons/**/*.svg"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Сгенерируйте спрайт
|
||||
|
||||
Передайте команде путь к конфигу:
|
||||
|
||||
```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` создаётся автоматически и полностью заменяется при каждой генерации. Не редактируйте его содержимое вручную.
|
||||
|
||||
### 4. Используйте иконку
|
||||
|
||||
В `index.html` укажите путь к созданному `sprite.svg`. После `#` добавьте имя нужной иконки без расширения `.svg`:
|
||||
|
||||
```html
|
||||
<svg
|
||||
width="24"
|
||||
height="24"
|
||||
aria-label="Готово"
|
||||
>
|
||||
<use href="./assets/app-icons/.svg-sprite/sprite.svg#check"></use>
|
||||
</svg>
|
||||
```
|
||||
|
||||
Иконка из файла `check.svg` будет доступна как `#check`.
|
||||
|
||||
## Дебаг и превью
|
||||
|
||||
`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-файл в корне сайта, предназначенный только для разработки и проверки иконок.
|
||||
@@ -1,113 +1,4 @@
|
||||
# Next.js App Router
|
||||
# Guides Next.js App Router перемещены
|
||||
|
||||
[← Главная](../../README_RU.md)
|
||||
|
||||
Поддерживаются два явных режима:
|
||||
|
||||
| Сборщик | Mode key |
|
||||
|---|---|
|
||||
| Turbopack | `next@app/turbopack` |
|
||||
| Webpack 5 | `next@app/webpack` |
|
||||
|
||||
## 1. Установите пакет
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
## 2. Создайте sprite-модуль
|
||||
|
||||
```text
|
||||
src/ui/file-manager/svg-sprite/
|
||||
├── icons/
|
||||
│ ├── check.svg
|
||||
│ └── folder.svg
|
||||
├── index.ts
|
||||
└── svg-sprite.config.ts
|
||||
```
|
||||
|
||||
```ts
|
||||
// src/ui/file-manager/svg-sprite/svg-sprite.config.ts
|
||||
import { defineSpriteConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default defineSpriteConfig({
|
||||
mode: 'next@app/turbopack',
|
||||
name: 'file-manager',
|
||||
description: 'Иконки файлового менеджера',
|
||||
})
|
||||
```
|
||||
|
||||
Корневой barrel принадлежит приложению:
|
||||
|
||||
```ts
|
||||
// src/ui/file-manager/svg-sprite/index.ts
|
||||
export * from './.svg-sprite'
|
||||
```
|
||||
|
||||
## 3. Добавьте генерацию
|
||||
|
||||
Для Turbopack:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprite:file-manager": "svg-sprites src/ui/file-manager/svg-sprite/svg-sprite.config.ts",
|
||||
"predev": "npm run sprite:file-manager",
|
||||
"prebuild": "npm run sprite:file-manager"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Для Webpack замените mode key на `next@app/webpack`.
|
||||
|
||||
До импорта generated-модуля выполните первую генерацию:
|
||||
|
||||
```bash
|
||||
npm run sprite:file-manager
|
||||
```
|
||||
|
||||
## 4. Используйте в Server Component
|
||||
|
||||
Generated-компонент не содержит `'use client'`, поэтому его можно импортировать непосредственно в `page.tsx` или `layout.tsx`:
|
||||
|
||||
```tsx
|
||||
import { FileManagerIcon } from '@/ui/file-manager/svg-sprite'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<main>
|
||||
<FileManagerIcon icon="folder" width={24} height={24} />
|
||||
</main>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Next.js выпустит отдельный SVG asset с content hash. Один generated-код используется при SSR и в браузере без расхождения URL.
|
||||
|
||||
## 5. Добавьте SpriteViewer
|
||||
|
||||
Viewer интерактивен, поэтому для него нужна отдельная Client Component граница:
|
||||
|
||||
```tsx
|
||||
'use client'
|
||||
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('@/ui/file-manager/svg-sprite/.svg-sprite/svg-sprite.manifest.js'),
|
||||
]
|
||||
|
||||
export default function SpritesPage() {
|
||||
return <SpriteViewer sources={sources} />
|
||||
}
|
||||
```
|
||||
|
||||
## Проверка сборщика
|
||||
|
||||
Запустите build script проекта, настроенный на выбранный сборщик:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
Build script и mode key генератора должны указывать один и тот же сборщик.
|
||||
- [App Router + Turbopack](guides/next-app-turbopack.md)
|
||||
- [App Router + Webpack](guides/next-app-webpack.md)
|
||||
|
||||
@@ -1,105 +1,4 @@
|
||||
# Next.js Pages Router
|
||||
# Guides Next.js Pages Router перемещены
|
||||
|
||||
[← Главная](../../README_RU.md)
|
||||
|
||||
Поддерживаются два явных режима:
|
||||
|
||||
| Сборщик | Mode key |
|
||||
|---|---|
|
||||
| Turbopack | `next@pages/turbopack` |
|
||||
| Webpack 5 | `next@pages/webpack` |
|
||||
|
||||
## 1. Установите пакет
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
## 2. Создайте sprite-модуль
|
||||
|
||||
```text
|
||||
src/ui/file-manager/svg-sprite/
|
||||
├── icons/
|
||||
│ ├── check.svg
|
||||
│ └── folder.svg
|
||||
├── index.ts
|
||||
└── svg-sprite.config.ts
|
||||
```
|
||||
|
||||
```ts
|
||||
// src/ui/file-manager/svg-sprite/svg-sprite.config.ts
|
||||
import { defineSpriteConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default defineSpriteConfig({
|
||||
mode: 'next@pages/webpack',
|
||||
name: 'file-manager',
|
||||
description: 'Иконки файлового менеджера',
|
||||
})
|
||||
```
|
||||
|
||||
Корневой barrel принадлежит приложению:
|
||||
|
||||
```ts
|
||||
// src/ui/file-manager/svg-sprite/index.ts
|
||||
export * from './.svg-sprite'
|
||||
```
|
||||
|
||||
## 3. Добавьте генерацию
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprite:file-manager": "svg-sprites src/ui/file-manager/svg-sprite/svg-sprite.config.ts",
|
||||
"predev": "npm run sprite:file-manager",
|
||||
"prebuild": "npm run sprite:file-manager"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Для Turbopack замените mode key на `next@pages/turbopack`.
|
||||
|
||||
До импорта generated-модуля выполните первую генерацию:
|
||||
|
||||
```bash
|
||||
npm run sprite:file-manager
|
||||
```
|
||||
|
||||
## 4. Используйте на странице
|
||||
|
||||
```tsx
|
||||
import { FileManagerIcon } from '@/ui/file-manager/svg-sprite'
|
||||
|
||||
export default function FilesPage() {
|
||||
return <FileManagerIcon icon="folder" width={24} height={24} />
|
||||
}
|
||||
|
||||
export function getServerSideProps() {
|
||||
return { props: {} }
|
||||
}
|
||||
```
|
||||
|
||||
Компонент одинаково работает при SSR, SSG и клиентских переходах. Next.js выпускает отдельный SVG asset с content hash.
|
||||
|
||||
## 5. Добавьте SpriteViewer
|
||||
|
||||
```tsx
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('@/ui/file-manager/svg-sprite/.svg-sprite/svg-sprite.manifest.js'),
|
||||
]
|
||||
|
||||
export default function SpritesPage() {
|
||||
return <SpriteViewer sources={sources} />
|
||||
}
|
||||
```
|
||||
|
||||
## Проверка сборщика
|
||||
|
||||
Запустите build script проекта, настроенный на выбранный сборщик:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
Build script и mode key генератора должны указывать один и тот же сборщик.
|
||||
- [Pages Router + Turbopack](guides/next-pages-turbopack.md)
|
||||
- [Pages Router + Webpack](guides/next-pages-webpack.md)
|
||||
|
||||
@@ -1,147 +1,3 @@
|
||||
# Программный API
|
||||
# Программный API перемещён
|
||||
|
||||
[← Главная](../../README_RU.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',
|
||||
)
|
||||
```
|
||||
|
||||
Для 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',
|
||||
inputFolder: './assets',
|
||||
inputFiles: ['../../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',
|
||||
inputFiles: [
|
||||
'../../shared/search.svg',
|
||||
'../../shared/settings.svg',
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
## Конфигурация
|
||||
|
||||
```ts
|
||||
import { defineSpriteConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default defineSpriteConfig({
|
||||
mode: 'react@vite',
|
||||
name: 'file-manager',
|
||||
description: 'Иконки файлового менеджера',
|
||||
inputFolder: './icons',
|
||||
inputFiles: ['../../shared/check.svg'],
|
||||
transform: {
|
||||
removeSize: true,
|
||||
replaceColors: true,
|
||||
addTransition: true,
|
||||
},
|
||||
generatedNotice: true,
|
||||
})
|
||||
```
|
||||
|
||||
`defineSpriteConfig` является identity helper для TypeScript autocomplete. JS может экспортировать тот же объект через `export default`, а JSON содержит объект непосредственно.
|
||||
|
||||
## Специализированные обёртки
|
||||
|
||||
Специализированные функции доступны как обёртки над `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 {
|
||||
loadSpriteConfig,
|
||||
resolveSpriteConfig,
|
||||
validateSpriteConfig,
|
||||
} from '@gromlab/svg-sprites'
|
||||
```
|
||||
|
||||
- `loadSpriteConfig(file)` загружает явно указанный `.ts`, `.js` или `.json` файл.
|
||||
- `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.
|
||||
|
||||
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-модулей приложения.
|
||||
Canonical документ: [программный API](reference/programmatic-api.md).
|
||||
|
||||
@@ -1,125 +1,3 @@
|
||||
# React + Vite
|
||||
# Guide React + Vite перемещён
|
||||
|
||||
[← Главная](../../README_RU.md)
|
||||
|
||||
Краткая инструкция по установке и использованию SVG-спрайтов в проекте на React и Vite.
|
||||
|
||||
В результате вы получите типизированный React-компонент и отдельный кешируемый SVG asset.
|
||||
|
||||
## 1. Установите пакет
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
## 2. Создайте папку спрайта
|
||||
|
||||
```text
|
||||
src/ui/file-manager/svg-sprite/
|
||||
├── icons/
|
||||
│ ├── check.svg
|
||||
│ └── folder.svg
|
||||
├── index.ts
|
||||
└── svg-sprite.config.ts
|
||||
```
|
||||
|
||||
Поместите исходные SVG-файлы в `icons/`.
|
||||
|
||||
## 3. Добавьте конфиг
|
||||
|
||||
```ts
|
||||
// src/ui/file-manager/svg-sprite/svg-sprite.config.ts
|
||||
import { defineSpriteConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default defineSpriteConfig({
|
||||
mode: 'react@vite',
|
||||
name: 'file-manager',
|
||||
description: 'Иконки файлового менеджера',
|
||||
})
|
||||
```
|
||||
|
||||
Корневой barrel принадлежит приложению и явно возвращает generated API:
|
||||
|
||||
```ts
|
||||
// src/ui/file-manager/svg-sprite/index.ts
|
||||
export * from './.svg-sprite'
|
||||
```
|
||||
|
||||
По умолчанию SVG берутся из `./icons`. Общие иконки из других папок можно добавить через `inputFiles`: папка и список объединяются в один спрайт.
|
||||
|
||||
Полный список опций находится в разделе [«Единая конфигурация»](reference.md#единая-конфигурация).
|
||||
|
||||
## 4. Добавьте генерацию в package.json
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprite:file-manager": "svg-sprites src/ui/file-manager/svg-sprite/svg-sprite.config.ts",
|
||||
"predev": "npm run sprite:file-manager",
|
||||
"prebuild": "npm run sprite:file-manager",
|
||||
"pretypecheck": "npm run sprite:file-manager"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Generated-файлы исключаются из Git, поэтому генерация должна выполняться перед `dev`, `build` и `typecheck`.
|
||||
|
||||
Первый запуск:
|
||||
|
||||
```bash
|
||||
npm run sprite:file-manager
|
||||
```
|
||||
|
||||
## 5. Используйте компонент
|
||||
|
||||
Имя `file-manager` преобразуется в `FileManagerIcon`:
|
||||
|
||||
```tsx
|
||||
import { FileManagerIcon } from './svg-sprite'
|
||||
|
||||
export const OpenFolderButton = () => (
|
||||
<button type="button">
|
||||
<FileManagerIcon icon="folder" width={24} height={24} />
|
||||
Открыть
|
||||
</button>
|
||||
)
|
||||
```
|
||||
|
||||
Значение `icon` проверяется TypeScript по именам файлов:
|
||||
|
||||
```tsx
|
||||
<FileManagerIcon icon="check" /> // допустимо
|
||||
<FileManagerIcon icon="unknown" /> // ошибка TypeScript
|
||||
```
|
||||
|
||||
Типы, способы отображения и управление цветами описаны в [техническом справочнике](reference.md#react-компонент-и-typescript).
|
||||
|
||||
Vite выпустит спрайт отдельным файлом вида `assets/sprite-<hash>.svg`. SVG path-данные не попадут в JavaScript.
|
||||
|
||||
## 6. Добавьте debug-страницу
|
||||
|
||||
После подключения иконок можно вывести все React-спрайты через `SpriteViewer`:
|
||||
|
||||
```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="Иконки проекта" />
|
||||
)
|
||||
```
|
||||
|
||||
Vite автоматически найдёт generated manifest каждого React-спрайта. Шаблон `import.meta.glob` должен быть строковым литералом, а генерация должна выполниться до запуска Vite.
|
||||
|
||||
Размещайте Viewer только на debug-маршруте или во внутреннем инструменте.
|
||||
|
||||
## Если что-то не работает
|
||||
|
||||
- Нет `.svg-sprite/index.js`: запустите `npm run sprite:file-manager`.
|
||||
- Viewer не видит спрайт: проверьте glob-путь к `.svg-sprite/svg-sprite.manifest.js`.
|
||||
- Ошибка `Refusing to overwrite a user file`: в generated-пути находится пользовательский файл.
|
||||
- Иконка не меняет цвет: используйте `color` или `--icon-color-N`.
|
||||
Canonical guide: [React + Vite](guides/react-vite.md).
|
||||
|
||||
@@ -1,129 +1,3 @@
|
||||
# React + Webpack 5
|
||||
# Guide React + Webpack перемещён
|
||||
|
||||
[← Главная](../../README_RU.md)
|
||||
|
||||
Краткая инструкция по установке и использованию SVG-спрайтов в проекте на React и Webpack 5.
|
||||
|
||||
В результате вы получите типизированный React-компонент и отдельный SVG asset через Webpack Asset Modules.
|
||||
|
||||
## 1. Установите пакет
|
||||
|
||||
```bash
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
## 2. Создайте папку спрайта
|
||||
|
||||
```text
|
||||
src/ui/file-manager/svg-sprite/
|
||||
├── icons/
|
||||
│ ├── check.svg
|
||||
│ └── folder.svg
|
||||
├── index.ts
|
||||
└── svg-sprite.config.ts
|
||||
```
|
||||
|
||||
Поместите исходные SVG-файлы в `icons/`.
|
||||
|
||||
## 3. Добавьте конфиг
|
||||
|
||||
```ts
|
||||
// src/ui/file-manager/svg-sprite/svg-sprite.config.ts
|
||||
import { defineSpriteConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default defineSpriteConfig({
|
||||
mode: 'react@webpack',
|
||||
name: 'file-manager',
|
||||
description: 'Иконки файлового менеджера',
|
||||
})
|
||||
```
|
||||
|
||||
Корневой barrel принадлежит приложению и явно возвращает generated API:
|
||||
|
||||
```ts
|
||||
// src/ui/file-manager/svg-sprite/index.ts
|
||||
export * from './.svg-sprite'
|
||||
```
|
||||
|
||||
По умолчанию SVG берутся из `./icons`. Общие иконки из других папок можно добавить через `inputFiles`: папка и список объединяются в один спрайт.
|
||||
|
||||
Полный список опций находится в разделе [«Единая конфигурация»](reference.md#единая-конфигурация).
|
||||
|
||||
## 4. Добавьте генерацию в package.json
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprite:file-manager": "svg-sprites src/ui/file-manager/svg-sprite/svg-sprite.config.ts",
|
||||
"predev": "npm run sprite:file-manager",
|
||||
"prebuild": "npm run sprite:file-manager",
|
||||
"pretypecheck": "npm run sprite:file-manager"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Generated-файлы исключаются из Git, поэтому генерация должна выполняться перед `dev`, `build` и `typecheck`.
|
||||
|
||||
Первый запуск:
|
||||
|
||||
```bash
|
||||
npm run sprite:file-manager
|
||||
```
|
||||
|
||||
## 5. Используйте компонент
|
||||
|
||||
```tsx
|
||||
import { FileManagerIcon } from './svg-sprite'
|
||||
|
||||
export const OpenFolderButton = () => (
|
||||
<button type="button">
|
||||
<FileManagerIcon icon="folder" width={24} height={24} />
|
||||
Открыть
|
||||
</button>
|
||||
)
|
||||
```
|
||||
|
||||
Значение `icon` проверяется TypeScript по именам файлов:
|
||||
|
||||
```tsx
|
||||
<FileManagerIcon icon="folder" /> // допустимо
|
||||
<FileManagerIcon icon="missing" /> // ошибка TypeScript
|
||||
```
|
||||
|
||||
Типы, способы отображения и управление цветами описаны в [техническом справочнике](reference.md#react-компонент-и-typescript).
|
||||
|
||||
Webpack обработает generated `new URL('./sprite.svg', import.meta.url)` через Asset Modules и выпустит отдельный SVG asset.
|
||||
|
||||
Если проект уже использует собственный SVG loader, убедитесь, что он не перехватывает generated `sprite.svg` вместо Asset Modules.
|
||||
|
||||
Generated-компонент импортирует `react/react-component.module.css`, поэтому Webpack должен обрабатывать CSS Modules через `css-loader` и `style-loader` либо `MiniCssExtractPlugin`. Если TypeScript-проект не содержит декларации для CSS Modules, добавьте её отдельно.
|
||||
|
||||
## 6. Добавьте debug-страницу
|
||||
|
||||
Webpack не поддерживает Vite API `import.meta.glob`, поэтому передайте статические loaders:
|
||||
|
||||
```tsx
|
||||
import { SpriteViewer } from '@gromlab/svg-sprites/react'
|
||||
|
||||
const sources = [
|
||||
() => import('./ui/file-manager/svg-sprite/.svg-sprite/svg-sprite.manifest.js'),
|
||||
() => import('./ui/navigation/svg-sprite/.svg-sprite/svg-sprite.manifest.js'),
|
||||
]
|
||||
|
||||
export const IconsDebugPage = () => (
|
||||
<SpriteViewer sources={sources} title="Иконки проекта" />
|
||||
)
|
||||
```
|
||||
|
||||
Пути в `import()` должны быть строковыми литералами. Webpack создаст chunks для манифестов и свяжет их с SVG assets.
|
||||
|
||||
Размещайте Viewer только на debug-маршруте или во внутреннем инструменте.
|
||||
|
||||
## Если что-то не работает
|
||||
|
||||
- Нет `.svg-sprite/index.js`: запустите `npm run sprite:file-manager`.
|
||||
- Viewer не загружает спрайт: проверьте путь в `import()` к `.svg-sprite/svg-sprite.manifest.js`.
|
||||
- Неверный URL asset: проверьте `output.publicPath`.
|
||||
- SVG перехватывает другой loader: исключите generated sprite из несовместимого правила.
|
||||
|
||||
Для Next.js используйте отдельные mode key из руководств [App Router](next-app.md) и [Pages Router](next-pages.md).
|
||||
Canonical guide: [React + Webpack](guides/react-webpack.md).
|
||||
|
||||
@@ -1,555 +1,3 @@
|
||||
# Технический справочник
|
||||
# Технический справочник перемещён
|
||||
|
||||
[← Главная](../../README_RU.md)
|
||||
|
||||
Справочник по конфигурации, generated API и поведению `@gromlab/svg-sprites`. Пошаговую установку смотрите в руководстве для вашего стека:
|
||||
|
||||
- [Next.js App Router](next-app.md)
|
||||
- [Next.js Pages Router](next-pages.md)
|
||||
- [React + Vite](react-vite.md)
|
||||
- [React + Webpack 5](react-webpack.md)
|
||||
|
||||
## Требования
|
||||
|
||||
- Node.js 18 или новее;
|
||||
- пакет распространяется как ESM и подключается через `import`;
|
||||
- React 18 или 19 требуется для generated-компонентов и `@gromlab/svg-sprites/react`;
|
||||
- для типизации package exports используйте TypeScript 5+ с `moduleResolution: "bundler"`, `"node16"` или `"nodenext"`.
|
||||
|
||||
Пакет устанавливается как development dependency:
|
||||
|
||||
```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` |
|
||||
| React + Vite | `react@vite` |
|
||||
| React + Webpack 5 | `react@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.ts`.
|
||||
|
||||
Если передан каталог, все настройки берутся из CLI. Если передан config-файл, CLI-параметры перекрывают значения файла. Общий порядок: `defaults → config → CLI`.
|
||||
|
||||
Доступны `--mode`, `--name`, `--description`, `--input-folder`, повторяемый `--input-file`, а также пары `--remove-size`/`--no-remove-size`, `--replace-colors`/`--no-replace-colors`, `--add-transition`/`--no-add-transition` и `--generated-notice`/`--no-generated-notice`. Переданные transform-флаги перекрывают отдельные поля, а хотя бы один `--input-file` заменяет весь массив `inputFiles` из config.
|
||||
|
||||
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: 'Общие иконки приложения',
|
||||
inputFolder: './local-icons',
|
||||
inputFiles: [
|
||||
'../../assets/icons/search.svg',
|
||||
'../../assets/icons/settings.svg',
|
||||
],
|
||||
transform: {
|
||||
removeSize: true,
|
||||
replaceColors: true,
|
||||
addTransition: true,
|
||||
},
|
||||
generatedNotice: true,
|
||||
})
|
||||
```
|
||||
|
||||
| Опция | Тип | По умолчанию | Назначение |
|
||||
|---|---|---|---|
|
||||
| `mode` | `SpriteMode` | Нет | Режим генерации; можно передать через CLI/API |
|
||||
| `name` | `string` | Выводится из каталога | Имя спрайта, компонента и публичных типов |
|
||||
| `description` | `string` | Нет | Описание для типов и debug manifest |
|
||||
| `inputFolder` | `string` | `./icons` | Каталог с SVG относительно корня модуля |
|
||||
| `inputFiles` | `string[]` | `[]` | Пути к отдельным SVG относительно корня модуля |
|
||||
| `transform` | `TransformOptions` | Все включены | Настройки подготовки SVG |
|
||||
| `generatedNotice` | `boolean` | `true` | Полное или короткое предупреждение в generated-файлах |
|
||||
|
||||
### Имя спрайта
|
||||
|
||||
`name` записывается в kebab-case и должно начинаться с латинской буквы:
|
||||
|
||||
```text
|
||||
app → AppIcon
|
||||
file-manager → FileManagerIcon
|
||||
```
|
||||
|
||||
Если `name` не задано, генератор выводит его из каталога. Для каталога с именем `svg-sprite` или `svg-sprites` используется имя родительского каталога.
|
||||
|
||||
### Источники иконок
|
||||
|
||||
`inputFolder` и `inputFiles` объединяются в один набор. Это позволяет хранить локальные SVG рядом с модулем и добавлять общие иконки из других частей проекта без копирования.
|
||||
|
||||
Если `inputFiles` заполнен, а неявного каталога `./icons` нет, генерация работает только по списку файлов. Явно указанная отсутствующая `inputFolder` считается ошибкой.
|
||||
|
||||
Каталог сканируется только на первом уровне. Вложенные каталоги рекурсивно не обходятся. Для вложенной структуры перечислите точные пути через `inputFiles`.
|
||||
|
||||
Одинаковые абсолютные пути дедуплицируются. Разные SVG с одинаковым именем файла считаются конфликтом, потому что публичное имя иконки выводится из basename.
|
||||
|
||||
## Generated-модуль
|
||||
|
||||
После генерации React- или Next.js-каталог спрайта выглядит так:
|
||||
|
||||
```text
|
||||
app-icons/
|
||||
├── .gitignore
|
||||
├── svg-sprite.config.ts
|
||||
├── index.ts # необязательный пользовательский barrel
|
||||
└── .svg-sprite/
|
||||
├── state.json
|
||||
├── 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` | Production exports компонента и runtime-списка имён |
|
||||
| `.svg-sprite/index.d.ts` | Публичные декларации компонента, props, стилей и 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-модулей |
|
||||
| `.svg-sprite/state.json` | Mode, версия контракта и список управляемых файлов |
|
||||
|
||||
Standalone-контракты не создают каталог `react/`. Bare `standalone` содержит только
|
||||
runtime asset и deployment-neutral manifest data:
|
||||
|
||||
```text
|
||||
.svg-sprite/
|
||||
├── state.json
|
||||
├── sprite.svg
|
||||
└── svg-sprite.manifest.json
|
||||
```
|
||||
|
||||
`standalone@vite` и `standalone@webpack` дополнительно создают `index.*`,
|
||||
`icon-data.*` и resolved `svg-sprite.manifest.*`.
|
||||
|
||||
Генератор перезаписывает и удаляет только файлы со своим marker. Если в managed-пути находится пользовательский файл, генерация завершается ошибкой. Корневой `index.ts` генератору не принадлежит; при необходимости создайте пользовательский barrel:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite'
|
||||
```
|
||||
|
||||
## 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',
|
||||
}}
|
||||
/>
|
||||
```
|
||||
|
||||
## Множественные спрайты
|
||||
|
||||
Каждый каталог с конфигом создаёт независимый компонент, типы, manifest и SVG asset:
|
||||
|
||||
```text
|
||||
app-icons → AppIcon → общие иконки
|
||||
analytics-icons → AnalyticsIcon → иконки страницы аналитики
|
||||
editor-icons → EditorIcon → иконки редактора
|
||||
```
|
||||
|
||||
Один исходный SVG можно добавить через `inputFiles` в несколько конфигураций. Копировать файл в каталоги каждого спрайта не требуется.
|
||||
|
||||
Для нескольких спрайтов добавьте отдельную CLI-команду для каждого каталога или объедините команды в общем npm script.
|
||||
|
||||
## Форматы и способы отображения
|
||||
|
||||
Все текущие modes создают формат `stack`.
|
||||
|
||||
| Формат | `<svg><use>` | `<img>` | CSS background |
|
||||
|---|---:|---:|---:|
|
||||
| `stack` | Да | Да | Да |
|
||||
|
||||
### Generated-компонент
|
||||
|
||||
Для React и Next.js используйте generated-компонент. Он знает внутренние ID, формирует URL и предоставляет TypeScript API:
|
||||
|
||||
```tsx
|
||||
<AppIcon icon="search" width={24} height={24} />
|
||||
```
|
||||
|
||||
### Вручную через `<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 `getIconsIconHref()` и 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-цвета. React/Next manifests получают вкладки React, 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
|
||||
|
||||
Современный sprite-модуль создаёт локальный `.gitignore` для:
|
||||
|
||||
```text
|
||||
/.svg-sprite/
|
||||
```
|
||||
|
||||
Локальный `.gitignore` следует один раз добавить в репозиторий. Он исключает остальные generated-файлы, поэтому генерацию нужно запускать перед командами, которые импортируют sprite-модуль:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprites": "svg-sprites src/ui/app-icons/svg-sprite.config.ts",
|
||||
"predev": "npm run sprites",
|
||||
"prebuild": "npm run sprites",
|
||||
"pretypecheck": "npm run sprites"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
CI должен устанавливать development dependencies и выполнять generation script до сборки или проверки типов.
|
||||
|
||||
Если в каталоге спрайта уже находится пользовательский `.gitignore` либо пользовательский файл внутри `.svg-sprite`, генератор не перезапишет его. Корневой `index.ts` остаётся пользовательским и может переэкспортировать generated API.
|
||||
|
||||
## Диагностика
|
||||
|
||||
- Нет `.svg-sprite/index.js`: запустите generation script до импорта generated-модуля.
|
||||
- Не найден источник: передайте существующий config-файл или каталог sprite-модуля.
|
||||
- Не указан mode: добавьте `mode` в config либо передайте `--mode`.
|
||||
- Иконка отсутствует в типе: проверьте `inputFiles`, расширение `.svg` и уровень вложенности `inputFolder`.
|
||||
- Конфликт имени: два разных SVG имеют одинаковый basename; переименуйте один файл.
|
||||
- `Refusing to overwrite a user file`: в managed-пути находится файл без generated marker.
|
||||
- Иконка не меняет цвет: используйте `<svg><use>` или generated-компонент и проверьте `replaceColors`.
|
||||
- Webpack выдаёт неверный URL: проверьте Asset Modules, `output.publicPath` и SVG loaders.
|
||||
- Static sprite возвращает 404: проверьте post-generation copy или server alias и не передавайте filesystem `spritePath` в HTML.
|
||||
- Viewer не видит спрайт: проверьте путь к `.svg-sprite/svg-sprite.manifest.js` и выполните генерацию до запуска приложения.
|
||||
- Build и mode не совпадают: используйте target, соответствующий фактическому сборщику.
|
||||
|
||||
Для собственного orchestration и низкоуровневой компиляции смотрите [Программный API](programmatic-api.md).
|
||||
Canonical документ: [технический справочник](reference/technical.md).
|
||||
|
||||
4
docs/ru/reference/README.md
Normal file
4
docs/ru/reference/README.md
Normal file
@@ -0,0 +1,4 @@
|
||||
# Справочники
|
||||
|
||||
- [Технический справочник](technical.md)
|
||||
- [Программный API](programmatic-api.md)
|
||||
147
docs/ru/reference/programmatic-api.md
Normal file
147
docs/ru/reference/programmatic-api.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# Программный 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',
|
||||
)
|
||||
```
|
||||
|
||||
Для 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 содержит объект непосредственно.
|
||||
|
||||
## Специализированные обёртки
|
||||
|
||||
Специализированные функции доступны как обёртки над `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 {
|
||||
loadSpriteConfig,
|
||||
resolveSpriteConfig,
|
||||
validateSpriteConfig,
|
||||
} from '@gromlab/svg-sprites'
|
||||
```
|
||||
|
||||
- `loadSpriteConfig(file)` загружает явно указанный `.ts`, `.js` или `.json` файл.
|
||||
- `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.
|
||||
|
||||
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-модулей приложения.
|
||||
631
docs/ru/reference/technical.md
Normal file
631
docs/ru/reference/technical.md
Normal file
@@ -0,0 +1,631 @@
|
||||
# Технический справочник
|
||||
|
||||
[Индекс документации](../README.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)
|
||||
|
||||
## Требования
|
||||
|
||||
- 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 --package=@gromlab/svg-sprites@latest svg-sprites path/to/svg-sprite.config.ts
|
||||
```
|
||||
|
||||
Устанавливайте пакет как 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` |
|
||||
| React + Vite | `react@vite` |
|
||||
| React + Webpack 5 | `react@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.ts`.
|
||||
|
||||
Если передан каталог, все настройки берутся из CLI. Если передан config-файл, CLI-параметры перекрывают значения файла. Общий порядок: `defaults → config → CLI`.
|
||||
|
||||
Доступны `--mode`, `--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 |
|
||||
| `name` | `string` | Выводится из каталога | Имя спрайта, компонента и публичных типов |
|
||||
| `description` | `string` | Нет | Описание для типов и debug manifest |
|
||||
| `input` | `string \| string[]` | `./icons` | Папки, SVG-файлы и glob-паттерны относительно папки конфига |
|
||||
| `transform` | `TransformOptions` | Все включены | Настройки подготовки SVG |
|
||||
| `generatedNotice` | `boolean` | `true` | Полное или короткое предупреждение в generated-файлах |
|
||||
|
||||
### Имя спрайта
|
||||
|
||||
`name` записывается в kebab-case и должно начинаться с латинской буквы:
|
||||
|
||||
```text
|
||||
app → AppIcon
|
||||
file-manager → FileManagerIcon
|
||||
```
|
||||
|
||||
Если `name` не задано, генератор выводит его из каталога. Для каталога с именем `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 задаёт публичное имя иконки.
|
||||
|
||||
## Generated-модуль
|
||||
|
||||
После генерации React- или Next.js-каталог спрайта выглядит так:
|
||||
|
||||
```text
|
||||
app-icons/
|
||||
├── .gitignore
|
||||
├── svg-sprite.config.ts
|
||||
├── 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-компонент.
|
||||
|
||||
Генератор перезаписывает и удаляет только файлы со своим marker. Если в managed-пути находится пользовательский файл, генерация завершается ошибкой. Корневой `index.ts` генератору не принадлежит; при необходимости создайте пользовательский barrel:
|
||||
|
||||
```ts
|
||||
export * from './.svg-sprite'
|
||||
```
|
||||
|
||||
## 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',
|
||||
}}
|
||||
/>
|
||||
```
|
||||
|
||||
## Множественные спрайты
|
||||
|
||||
Каждый каталог с конфигом создаёт независимый компонент, типы, manifest и SVG asset:
|
||||
|
||||
```text
|
||||
app-icons → AppIcon → общие иконки
|
||||
analytics-icons → AnalyticsIcon → иконки страницы аналитики
|
||||
editor-icons → EditorIcon → иконки редактора
|
||||
```
|
||||
|
||||
Один исходный SVG можно добавить через `input` в несколько конфигураций. Копировать файл в каталоги каждого спрайта не требуется.
|
||||
|
||||
Для нескольких спрайтов добавьте отдельную CLI-команду для каждого каталога или объедините команды в общем npm script.
|
||||
|
||||
## Форматы и способы отображения
|
||||
|
||||
Все текущие modes создают формат `stack`.
|
||||
|
||||
| Формат | `<svg><use>` | `<img>` | CSS background |
|
||||
|---|---:|---:|---:|
|
||||
| `stack` | Да | Да | Да |
|
||||
|
||||
### Generated-компонент
|
||||
|
||||
Для React и Next.js используйте generated React-компонент. Он знает внутренние ID, формирует URL и предоставляет TypeScript API:
|
||||
|
||||
```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 `getIconsIconHref()` и 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-цвета. React/Next manifests получают вкладки React, 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 --package=@gromlab/svg-sprites@latest 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 до сборки или проверки типов. Для воспроизводимости замените `latest` на точную версию. Локальная установка package не нужна, если CI не использует Viewer, package-типы config или программный API.
|
||||
|
||||
Bare `standalone` не создаёт и не изменяет `.gitignore`: приложение само решает, коммитить или игнорировать его `.svg-sprite/`. В остальных modes генератор не перезапишет пользовательский `.gitignore`. Он также откажется перезаписывать пользовательский файл внутри `.svg-sprite`. Корневой `index.ts` остаётся пользовательским и может переэкспортировать generated API.
|
||||
|
||||
## Диагностика
|
||||
|
||||
- Нет `.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`: в managed-пути находится файл без generated marker.
|
||||
- Иконка не меняет цвет: используйте `<svg><use>` или generated-компонент и проверьте `replaceColors`.
|
||||
- Webpack выдаёт неверный URL: проверьте Asset Modules, `output.publicPath` и SVG loaders.
|
||||
- Static sprite возвращает 404: проверьте post-generation copy или server alias и не передавайте filesystem `spritePath` в HTML.
|
||||
- Viewer не видит спрайт: проверьте путь к `.svg-sprite/svg-sprite.manifest.js` и выполните генерацию до запуска приложения.
|
||||
- Build и mode не совпадают: используйте target, соответствующий фактическому сборщику.
|
||||
|
||||
Для собственного orchestration и низкоуровневой компиляции смотрите [Программный API](programmatic-api.md).
|
||||
Reference in New Issue
Block a user