Migrations

v0.8.0

The most featured release of @neodx/svg and the last one before the v1.0.0 release to maintain partial compatibility with the previous versions and provide a smooth migration path.

In this release we've redesigned the internals of the @neodx/svg library and made public API more stable and consistent.

• CLI Deprecation
• root -> inputRoot
• metadata simplification

CLI Deprecation

The CLI mode has been deprecated in favor of the programmatic API and will be removed in the v1.0.0 release.

Migration Steps

1. Replace CLI Usage with Programmatic API

   Instead of using the CLI command:

   yarn sprite --group --root assets -o public/sprite -d src/shared/ui/icon/sprite.gen.ts --reset-unknown-colors

   Use the programmatic API in your build script:

scripts/build-icons.ts

import { createSvgSpriteBuilder } from '@neodx/svg';

const builder = createSvgSpriteBuilder({
  // Base path for all svg files
  inputRoot: 'src/shared/ui/icon/assets',
  // Path to generated sprites types and runtime utilities
  metadata: 'src/shared/ui/icon/sprite.gen.ts',
  // Generated sprites output directory
  output: 'public/sprite'
});

await builder.load('**/*.svg');
await builder.build();

TIP

See all available options in the API Reference

2. Update Build Scripts

   If you were using the CLI in your package.json scripts:

   {
     "scripts": {
       "build:icons": "sprite --group --root assets"
     }
   }

   Create a new build script file (e.g., scripts/build-icons.ts):

scripts/build-icons.ts

import { createSvgSpriteBuilder } from '@neodx/svg';

const builder = createSvgSpriteBuilder({
  // Base path for all svg files
  inputRoot: 'src/shared/ui/icon/assets',
  // Path to generated sprites types and runtime utilities
  metadata: 'src/shared/ui/icon/sprite.gen.ts',
  // Generated sprites output directory
  output: 'public/sprite'
});

await builder.load('**/*.svg');
await builder.build();

TIP

See all available options in the API Reference

And update your package.json:

{
  "scripts": {
    "build:icons": "tsx scripts/build-icons.ts"
  }
}

3. Update CI/CD Pipelines

   If you are using the CLI in your CI/CD pipelines, update them to use the programmatic API instead.

root option was renamed to inputRoot

The root option was renamed to inputRoot to make it clearer that it's a root path for the input files.

metadata option was simplified, definitions and experimentalRuntime options were removed

The metadata option is now a string representing the metadata file path.

Previously, you could disable types or runtime values generation, but this was somewhat confusing.

vfsParams and logger options was removed

TIP

Mostly for Node API Usage

Now only vfs and log options are supported. Both of them are flexible and support multiple ways to provide them.