mirror of
https://github.com/gromlab-ru/svg-sprites.git
synced 2026-07-22 12:40:21 +03:00
S.Gromov
81df9027cd
- добавлены английские README и руководства с переключением языка - сборка скиллов разделена на английскую и русскую версии - локализованные документы включены в npm-пакет
97 lines
3.1 KiB
Markdown
97 lines
3.1 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.
|
|
|
|
## CLI
|
|
|
|
The CLI now always requires an explicit `--mode` and a path to the configuration directory:
|
|
|
|
```text
|
|
svg-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`.
|
|
|
|
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.
|
|
|
|
Run:
|
|
|
|
```bash
|
|
svg-sprites --mode legacy .
|
|
```
|
|
|
|
## 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. 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`.
|