mirror of
https://github.com/gromlab-ru/svg-sprites.git
synced 2026-07-22 04:40:17 +03:00
S.Gromov
1b5b446d8f
- пакет указан как development dependency - команды переведены на локальный CLI без npx - удалены версионные ограничения Next.js - синхронизированы английская и русская документация и skills
123 lines
3.8 KiB
Markdown
123 lines
3.8 KiB
Markdown
# Migrating from 0.1.x to 1.0
|
|
|
|
[← Back to home](../../README.md)
|
|
|
|
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
|
|
"sprites": "svg-sprites"
|
|
→ "sprites": "svg-sprites --mode <mode> <path>"
|
|
```
|
|
|
|
Choose a mode based on your environment:
|
|
|
|
| Environment | 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` |
|
|
| Centralized legacy setup | `legacy` |
|
|
|
|
## React and Next.js
|
|
|
|
Instead of a root-level `svg-sprites.config.ts`, create a local `svg-sprite.config.ts` next to the icon set:
|
|
|
|
```ts
|
|
import { defineNextSpriteConfig } from '@gromlab/svg-sprites'
|
|
|
|
export default defineNextSpriteConfig({
|
|
name: 'global',
|
|
inputFolder: './icons',
|
|
})
|
|
```
|
|
|
|
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`:
|
|
|
|
```tsx
|
|
<GlobalIcon icon="check" />
|
|
```
|
|
|
|
To browse the icons, add `<SpriteViewer>` as a debug page in the application. A separate `preview.html` is available only in legacy mode.
|
|
|
|
## Legacy mode
|
|
|
|
If you need to preserve the centralized structure, rename the helper and the format fields:
|
|
|
|
```ts
|
|
import { defineLegacyConfig } from '@gromlab/svg-sprites'
|
|
|
|
export default defineLegacyConfig({
|
|
output: 'public/sprites',
|
|
preview: true,
|
|
sprites: [
|
|
{
|
|
name: 'icons',
|
|
input: 'src/assets/icons',
|
|
format: 'stack',
|
|
},
|
|
],
|
|
})
|
|
```
|
|
|
|
- `defineConfig` has been replaced with `defineLegacyConfig`;
|
|
- `sprites[].mode` has been renamed to `sprites[].format`;
|
|
- `generate` has been replaced with `generateLegacy`;
|
|
- `loadConfig` has been replaced with `loadLegacyConfig`;
|
|
- `publicPath` and generation of the old shared React component have been removed.
|
|
|
|
Add the local CLI to `package.json`:
|
|
|
|
```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`.
|
|
|
|
`compileSpriteContent` now returns `Promise<Uint8Array>` so that the public declarations do not require `@types/node` to be installed. In Node.js, the actual result is compatible with APIs that accept `Uint8Array`.
|
|
|
|
## After migration
|
|
|
|
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.
|