mirror of
https://github.com/gromlab-ru/svg-sprites.git
synced 2026-10-21 03:50:18 +03:00
docs: обновить установку и команды генерации
- пакет указан как development dependency - команды переведены на локальный CLI без npx - удалены версионные ограничения Next.js - синхронизированы английская и русская документация и skills
This commit is contained in:
+14
-14
@@ -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`:
|
||||
|
||||
+35
-9
@@ -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.
|
||||
|
||||
+16
-14
@@ -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.
|
||||
|
||||
+16
-16
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
+14
-14
@@ -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`:
|
||||
|
||||
+35
-9
@@ -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.
|
||||
|
||||
+16
-14
@@ -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 генератора должны указывать один и тот же сборщик.
|
||||
|
||||
+16
-16
@@ -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 генератора должны указывать один и тот же сборщик.
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
## 1. Установите пакет
|
||||
|
||||
```bash
|
||||
npm install @gromlab/svg-sprites
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
## 2. Создайте папку спрайта
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
## 1. Установите пакет
|
||||
|
||||
```bash
|
||||
npm install @gromlab/svg-sprites
|
||||
npm install --save-dev @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
## 2. Создайте папку спрайта
|
||||
|
||||
Reference in New Issue
Block a user