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

Migrating from 0.1.x to 1.0

← Back to home

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:

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:

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:

<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:

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:

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.