@solar-icons/codemod

Conservative, opt-in migrations for Solar Icons v2.

Run a migration

Use the interactive assistant when running the migration by hand. It detects supported frameworks, asks for the React and Vue strategy when relevant, and requires confirmation before it writes files.

npx @solar-icons/codemod --interactive

Use arguments for scripts, CI, or repeatable migrations. The command previews changes unless --write is passed.

npx @solar-icons/codemod --react-v1-mode static
npx @solar-icons/codemod ./apps/web --react-v1-mode static --write
npx @solar-icons/codemod --json > solar-icons-migration.json

Run npx @solar-icons/codemod --help for every option. --cwd <path> remains available for existing scripts, but a directory argument is shorter.

React v1 strategy

--react-v1-mode static is the default and recommended mode. It converts a known weight to a per-style import, removing the prop for the smallest bundle.

--react-v1-mode dynamic preserves the old all-styles component model through @solar-icons/react/dynamic.

If a weight expression cannot be resolved while using static, the codemod safely uses dynamic for that icon and prints a file, line, column, code, and explanation.

Vue v1 strategy

--vue-v1-mode static follows the same per-style default for Vue single-file components. It rewrites supported <script> or <script setup> imports and their template tags. --vue-v1-mode dynamic preserves weight bindings through @solar-icons/vue/dynamic.

Nuxt v1 configuration

The Nuxt adapter renames solarIcons.prefix to solarIcons.namePrefix and upgrades the Nuxt module dependency. The removed #solar-icons/category alias is reported with its source location because the replacement depends on the individual icons and styles used by the application.

Svelte v1 imports

The Svelte adapter migrates per-style imports and deterministic direct category component imports. Category barrels and removed mirrored props are reported with source locations for manual follow-up.

Angular v1 imports

The Angular adapter renames static icon exports to their Solar-prefixed v2 names, updates TypeScript references and deterministic inline-template selectors. It reports external templates and removed mirrored inputs for manual review.

Manual follow-ups

The codemod reports, without rewriting, legacy providers and useSolar, category imports, default namespace imports, and removed mirrored props. These need an application-level decision and are linked to the v2 migration guide.

All 37 removed icon names are converted through an explicit v1-to-v2 mapping. The codemod also normalizes the six current catalogue aliases introduced by the file and chat naming cleanup (code-file, cloud-file, figma-file, chat-dots, chat-line, and chat-unread) to their canonical names while those old names remain available as deprecated compatibility exports.

Verification

pnpm test
pnpm test:fixtures

The runnable fixtures build pinned v1 applications, migrate a temporary copy, install the v2 beta, and build again.