svg-sprites/docs/ru/migration-1.md

Миграция с 0.1.x на 1.0

← Главная

Версия 1.0 разделяет локальную генерацию для React и Next.js и централизованный legacy-режим. Старый config нельзя смешивать с новым API в одном вызове CLI.

Установка

Установите пакет как development dependency, чтобы миграция использовала версию из lockfile проекта:

npm install --save-dev @gromlab/svg-sprites

CLI

CLI теперь всегда требует явный --mode и путь к каталогу конфигурации:

"sprites": "svg-sprites"
→ "sprites": "svg-sprites --mode <mode> <path>"

Выберите mode по окружению:

Окружение	Mode
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
Централизованная старая схема	legacy

React и Next.js

Вместо корневого svg-sprites.config.ts создайте локальный svg-sprite.config.ts рядом с набором иконок:

import { defineNextSpriteConfig } from '@gromlab/svg-sprites'

export default defineNextSpriteConfig({
  name: 'global',
  inputFolder: './icons',
})

Для обычного React используйте defineReactSpriteConfig. Папку и явный список общих SVG можно объединить через inputFolder и inputFiles.

Добавьте локальный CLI с выбранным mode в package.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:

<GlobalIcon icon="check" />

Для просмотра иконок добавьте <SpriteViewer> как debug-страницу приложения. Отдельный preview.html остаётся только в legacy-режиме.

Legacy-режим

Если централизованную структуру нужно сохранить, переименуйте helper и поля формата:

import { defineLegacyConfig } from '@gromlab/svg-sprites'

export default defineLegacyConfig({
  output: 'public/sprites',
  preview: true,
  sprites: [
    {
      name: 'icons',
      input: 'src/assets/icons',
      format: 'stack',
    },
  ],
})

• defineConfig заменён на defineLegacyConfig;
• sprites[].mode переименован в sprites[].format;
• generate заменён на generateLegacy;
• loadConfig заменён на loadLegacyConfig;
• publicPath и генерация старого общего React-компонента удалены.

Добавьте локальный CLI в package.json:

{
  "scripts": {
    "sprites": "svg-sprites --mode legacy ."
  }
}

Запустите его командой npm run sprites.

Программный API

Пакет распространяется только как ESM. Замените require() на import.

compileSpriteContent теперь возвращает Promise<Uint8Array>, чтобы публичные декларации не требовали установки @types/node. В Node.js фактический результат совместим с API, принимающими Uint8Array.

После миграции

1. Добавьте явную команду генерации перед dev, build и typecheck.
2. Создайте новый output и запустите проверку типов, пока старые artifacts остаются доступны.
3. Замените imports и проверьте иконки и цветовые переменные через SpriteViewer или legacy preview.html.
4. Только после этого удалите подтверждённые старые generated-файлы и устаревшие ignore rules, не затрагивая исходные SVG.