gromov/svg-sprites
1
0
Fork 0
mirror of https://github.com/gromlab-ru/svg-sprites.git synced 2026-07-22 04:40:17 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: обновить установку и команды генерации

Browse Source 
- пакет указан как development dependency
- команды переведены на локальный CLI без npx
- удалены версионные ограничения Next.js
- синхронизированы английская и русская документация и skills
This commit is contained in:
Сергей Громов
2026-07-11 18:23:41 +03:00
parent b3a3a8347a
commit 1b5b446d8f
40 changed files with 468 additions and 430 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/en/legacy.md
View File

@@ -7,7 +7,7 @@ A quick guide to generating centralized SVG sprites in `symbol` and `stack` form
## 1. Install the package
```bash
npm install @gromlab/svg-sprites
npm install --save-dev @gromlab/svg-sprites
```
## 2. Prepare the icons and config
@@ -37,10 +37,21 @@ export default defineLegacyConfig({
})
```
## 3. Run generation
## 3. Add generation
```json
{
"scripts": {
"sprites": "svg-sprites --mode legacy .",
"prebuild": "npm run sprites"
}
}
```
Run the local package through the script:
```bash
npx svg-sprites --mode legacy .
npm run sprites
```
Result:
@@ -61,17 +72,6 @@ With `preview: false`, the HTML file is not created. For the `stack` format, spe
</svg>
```
## 5. Add a package script
```json
{
"scripts": {
"sprites": "svg-sprites --mode legacy .",
"prebuild": "npm run sprites"
}
}
```
## Multiple sprites
Add multiple entries to `sprites`:

44
docs/en/migration-1.md
View File

@@ -4,13 +4,21 @@
Version 1.0 separates local generation for React and Next.js from the centralized legacy mode. The old config cannot be mixed with the new API in a single CLI invocation.
## Installation
Install the package as a development dependency so the migration uses the version recorded in the project lockfile:
```bash
npm install --save-dev @gromlab/svg-sprites
```
## CLI
The CLI now always requires an explicit `--mode` and a path to the configuration directory:
```text
svg-sprites
→ svg-sprites --mode <mode> <path>
"sprites": "svg-sprites"
→ "sprites": "svg-sprites --mode <mode> <path>"
```
Choose a mode based on your environment:
@@ -40,6 +48,18 @@ export default defineNextSpriteConfig({
For regular React, use `defineReactSpriteConfig`. A folder and an explicit list of shared SVG files can be combined using `inputFolder` and `inputFiles`.
Add the local CLI with the selected mode to `package.json`, for example:
```json
{
"scripts": {
"sprite:global": "svg-sprites --mode next@app/turbopack src/ui/global/svg-sprite"
}
}
```
Run it with `npm run sprite:global` before importing the generated component.
The old `publicPath` and `react` options are no longer needed. The generated module is created next to the config and adds its own `.gitignore`, while Vite, Webpack, or Next.js emits the SVG as a separate asset with a content hash.
The `<SvgSprite icon="..." />` component is replaced by a component whose name is derived from `name`:
@@ -76,12 +96,18 @@ export default defineLegacyConfig({
- `loadConfig` has been replaced with `loadLegacyConfig`;
- `publicPath` and generation of the old shared React component have been removed.
Run:
Add the local CLI to `package.json`:
```bash
svg-sprites --mode legacy .
```json
{
"scripts": {
"sprites": "svg-sprites --mode legacy ."
}
}
```
Run it with `npm run sprites`.
## Programmatic API
The package is distributed as ESM only. Replace `require()` with `import`.
@@ -90,7 +116,7 @@ The package is distributed as ESM only. Replace `require()` with `import`.
## After migration
1. Remove the old generated files and rules that ignored the entire directory containing the source icons.
2. Add an explicit generation command before `dev`, `build`, and `typecheck`.
3. Run generation and type checking.
4. Check all icons and color variables using `SpriteViewer` or the legacy `preview.html`.
1. Add an explicit generation command before `dev`, `build`, and `typecheck`.
2. Generate the new output and run type checking while the old artifacts are still available.
3. Replace imports and verify the icons and color variables using `SpriteViewer` or the legacy `preview.html`.
4. Only then remove confirmed old generated files and obsolete ignore rules without deleting source SVGs.

30
docs/en/next-app.md
View File

@@ -4,15 +4,15 @@
Two explicit modes are supported:
| Bundler | Mode key | Next.js version |
|---|---|---|
| Turbopack | `next@app/turbopack` | 16.2+ |
| Webpack 5 | `next@app/webpack` | 13.4+ |
| Bundler | Mode key |
|---|---|
| Turbopack | `next@app/turbopack` |
| Webpack 5 | `next@app/webpack` |
## 1. Install the package
```bash
npm install @gromlab/svg-sprites
npm install --save-dev @gromlab/svg-sprites
```
## 2. Create a sprite module
@@ -49,7 +49,13 @@ For Turbopack:
}
```
For Webpack, replace the mode key with `next@app/webpack`. In Next 13–15, Webpack is used with the regular `next build` command; in Next 16, use `next build --webpack`.
For Webpack, replace the mode key with `next@app/webpack`.
Run the first generation before importing the generated module:
```bash
npm run sprite:file-manager
```
## 4. Use it in a Server Component
@@ -89,14 +95,10 @@ export default function SpritesPage() {
## Verify the bundler
```bash
# Turbopack
npx next build --turbopack
Run the project's build script configured for the selected bundler:
# Webpack 5
npx next build --webpack
```bash
npm run build
```
For Next 13–15 with Webpack, use `npx next build` without the flag.
The Next.js command and the generator mode key must target the same bundler.
The build script and the generator mode key must target the same bundler.

32
docs/en/next-pages.md
View File

@@ -4,17 +4,15 @@
Two explicit modes are supported:
| Bundler | Mode key | Next.js version |
|---|---|---|
| Turbopack | `next@pages/turbopack` | 16.2+ |
| Webpack 5 | `next@pages/webpack` | 12.2+ |
Next.js 12.2 requires React 18.
| Bundler | Mode key |
|---|---|
| Turbopack | `next@pages/turbopack` |
| Webpack 5 | `next@pages/webpack` |
## 1. Install the package
```bash
npm install @gromlab/svg-sprites
npm install --save-dev @gromlab/svg-sprites
```
## 2. Create a sprite module
@@ -49,7 +47,13 @@ export default defineNextSpriteConfig({
}
```
For Next.js 16.2 with Turbopack, replace the mode key with `next@pages/turbopack`.
For Turbopack, replace the mode key with `next@pages/turbopack`.
Run the first generation before importing the generated module:
```bash
npm run sprite:file-manager
```
## 4. Use it on a page
@@ -83,14 +87,10 @@ export default function SpritesPage() {
## Verify the bundler
```bash
# Turbopack
npx next build --turbopack
Run the project's build script configured for the selected bundler:
# Webpack 5
npx next build --webpack
```bash
npm run build
```
For Next 12–15 with Webpack, use `npx next build` without the flag.
The Next.js command and the generator mode key must target the same bundler.
The build script and the generator mode key must target the same bundler.

2
docs/en/react-vite.md
View File

@@ -9,7 +9,7 @@ The result is a typed React component and a separate cacheable SVG asset.
## 1. Install the package
```bash
npm install @gromlab/svg-sprites
npm install --save-dev @gromlab/svg-sprites
```
## 2. Create the sprite directory

2
docs/en/react-webpack.md
View File

@@ -9,7 +9,7 @@ The result is a typed React component and a separate SVG asset emitted through W
## 1. Install the package
```bash
npm install @gromlab/svg-sprites
npm install --save-dev @gromlab/svg-sprites
```
## 2. Create the sprite directory

28
docs/ru/legacy.md
View File

@@ -7,7 +7,7 @@
## 1. Установите пакет
```bash
npm install @gromlab/svg-sprites
npm install --save-dev @gromlab/svg-sprites
```
## 2. Подготовьте иконки и конфиг
@@ -37,10 +37,21 @@ export default defineLegacyConfig({
})
```
## 3. Запустите генерацию
## 3. Добавьте генерацию
```json
{
"scripts": {
"sprites": "svg-sprites --mode legacy .",
"prebuild": "npm run sprites"
}
}
```
Запустите локально установленный пакет через script:
```bash
npx svg-sprites --mode legacy .
npm run sprites
```
Результат:
@@ -61,17 +72,6 @@ public/sprites/
</svg>
```
## 5. Добавьте package script
```json
{
"scripts": {
"sprites": "svg-sprites --mode legacy .",
"prebuild": "npm run sprites"
}
}
```
## Несколько спрайтов
Добавьте несколько записей в `sprites`:

44
docs/ru/migration-1.md
View File

@@ -4,13 +4,21 @@
Версия 1.0 разделяет локальную генерацию для React и Next.js и централизованный legacy-режим. Старый config нельзя смешивать с новым API в одном вызове CLI.
## Установка
Установите пакет как development dependency, чтобы миграция использовала версию из lockfile проекта:
```bash
npm install --save-dev @gromlab/svg-sprites
```
## CLI
CLI теперь всегда требует явный `--mode` и путь к каталогу конфигурации:
```text
svg-sprites
→ svg-sprites --mode <mode> <path>
"sprites": "svg-sprites"
→ "sprites": "svg-sprites --mode <mode> <path>"
```
Выберите mode по окружению:
@@ -40,6 +48,18 @@ export default defineNextSpriteConfig({
Для обычного React используйте `defineReactSpriteConfig`. Папку и явный список общих SVG можно объединить через `inputFolder` и `inputFiles`.
Добавьте локальный CLI с выбранным mode в `package.json`, например:
```json
{
"scripts": {
"sprite:global": "svg-sprites --mode next@app/turbopack src/ui/global/svg-sprite"
}
}
```
Запустите его командой `npm run sprite:global` до импорта generated-компонента.
Старые `publicPath` и `react` больше не нужны. Generated-модуль создаётся рядом с конфигом, сам добавляет `.gitignore`, а Vite, Webpack или Next.js выпускает SVG как отдельный asset с content hash.
Компонент `<SvgSprite icon="..." />` заменяется компонентом, имя которого выводится из `name`:
@@ -76,12 +96,18 @@ export default defineLegacyConfig({
- `loadConfig` заменён на `loadLegacyConfig`;
- `publicPath` и генерация старого общего React-компонента удалены.
Запуск:
Добавьте локальный CLI в `package.json`:
```bash
svg-sprites --mode legacy .
```json
{
"scripts": {
"sprites": "svg-sprites --mode legacy ."
}
}
```
Запустите его командой `npm run sprites`.
## Программный API
Пакет распространяется только как ESM. Замените `require()` на `import`.
@@ -90,7 +116,7 @@ svg-sprites --mode legacy .
## После миграции
1. Удалите старые generated-файлы и правила, которые игнорировали целиком каталог с исходными иконками.
2. Добавьте явную команду генерации перед `dev`, `build` и `typecheck`.
3. Запустите генерацию и проверку типов.
4. Проверьте все иконки и цветовые переменные через `SpriteViewer` или legacy `preview.html`.
1. Добавьте явную команду генерации перед `dev`, `build` и `typecheck`.
2. Создайте новый output и запустите проверку типов, пока старые artifacts остаются доступны.
3. Замените imports и проверьте иконки и цветовые переменные через `SpriteViewer` или legacy `preview.html`.
4. Только после этого удалите подтверждённые старые generated-файлы и устаревшие ignore rules, не затрагивая исходные SVG.

30
docs/ru/next-app.md
View File

@@ -4,15 +4,15 @@
Поддерживаются два явных режима:
| Сборщик | Mode key | Версия Next.js |
|---|---|---|
| Turbopack | `next@app/turbopack` | 16.2+ |
| Webpack 5 | `next@app/webpack` | 13.4+ |
| Сборщик | Mode key |
|---|---|
| Turbopack | `next@app/turbopack` |
| Webpack 5 | `next@app/webpack` |
## 1. Установите пакет
```bash
npm install @gromlab/svg-sprites
npm install --save-dev @gromlab/svg-sprites
```
## 2. Создайте sprite-модуль
@@ -49,7 +49,13 @@ export default defineNextSpriteConfig({
}
```
Для Webpack замените mode key на `next@app/webpack`. В Next 13–15 Webpack используется обычной командой `next build`, в Next 16 — командой `next build --webpack`.
Для Webpack замените mode key на `next@app/webpack`.
До импорта generated-модуля выполните первую генерацию:
```bash
npm run sprite:file-manager
```
## 4. Используйте в Server Component
@@ -89,14 +95,10 @@ export default function SpritesPage() {
## Проверка сборщика
```bash
# Turbopack
npx next build --turbopack
Запустите build script проекта, настроенный на выбранный сборщик:
# Webpack 5
npx next build --webpack
```bash
npm run build
```
Для Next 13–15 с Webpack используйте `npx next build` без флага.
Команда Next.js и mode key генератора должны указывать один и тот же сборщик.
Build script и mode key генератора должны указывать один и тот же сборщик.

32
docs/ru/next-pages.md
View File

@@ -4,17 +4,15 @@
Поддерживаются два явных режима:
| Сборщик | Mode key | Версия Next.js |
|---|---|---|
| Turbopack | `next@pages/turbopack` | 16.2+ |
| Webpack 5 | `next@pages/webpack` | 12.2+ |
Для Next.js 12.2 требуется React 18.
| Сборщик | Mode key |
|---|---|
| Turbopack | `next@pages/turbopack` |
| Webpack 5 | `next@pages/webpack` |
## 1. Установите пакет
```bash
npm install @gromlab/svg-sprites
npm install --save-dev @gromlab/svg-sprites
```
## 2. Создайте sprite-модуль
@@ -49,7 +47,13 @@ export default defineNextSpriteConfig({
}
```
Для Next.js 16.2 с Turbopack замените mode key на `next@pages/turbopack`.
Для Turbopack замените mode key на `next@pages/turbopack`.
До импорта generated-модуля выполните первую генерацию:
```bash
npm run sprite:file-manager
```
## 4. Используйте на странице
@@ -83,14 +87,10 @@ export default function SpritesPage() {
## Проверка сборщика
```bash
# Turbopack
npx next build --turbopack
Запустите build script проекта, настроенный на выбранный сборщик:
# Webpack 5
npx next build --webpack
```bash
npm run build
```
Для Next 12–15 с Webpack используйте `npx next build` без флага.
Команда Next.js и mode key генератора должны указывать один и тот же сборщик.
Build script и mode key генератора должны указывать один и тот же сборщик.

2
docs/ru/react-vite.md
View File

@@ -9,7 +9,7 @@
## 1. Установите пакет
```bash
npm install @gromlab/svg-sprites
npm install --save-dev @gromlab/svg-sprites
```
## 2. Создайте папку спрайта

2
docs/ru/react-webpack.md
View File

@@ -9,7 +9,7 @@
## 1. Установите пакет
```bash
npm install @gromlab/svg-sprites
npm install --save-dev @gromlab/svg-sprites
```
## 2. Создайте папку спрайта