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:
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-файл в корне сайта, предназначенный только для разработки и проверки иконок.
|
||||
Reference in New Issue
Block a user