Current source version: 4.0.9

SVG to component compiler for modern JavaScript stacks.

SVGER-CLI builds optimized SVG components for React, React Native, Vue, Angular, Svelte, Solid, Preact, Lit, and vanilla JavaScript. This page is tied to the current implementation surface, not the older v4.0.3/v4.0.7 marketing copy previously deployed.

View on npm Commands and live testing View repository Optimizer guide Browser benchmark

At a glance

9framework targets

10CLI command groups

6official build/test integrations

15/15live runtime smoke assertions passed

Release and Governance Status

Implementation state

The repository source is at 4.0.9. Phase 0 safety containment, Phase 1 architecture evidence, and P2-201 parser research documents are present in the repository.

Publication state

npm still reports svger-cli latest as 4.0.8 until the v4.0.9 release is published and independently verified. P2-202 parser implementation remains blocked.

Gate	Current documentation position	Where to verify
Phase 0	Implementation complete; official publication gate still requires registry verification.	`docs/phase0-release-gate.md`, `reports/phase-0-report.md`
Phase 1	Local implementation evidence exists; compatibility rows remain approval-gated.	`reports/phase1-implementation-report.md`, `compatibility-ledger-v4.1.md`
Phase 2	P2-201 ADR and qualification plan are documentation/research only.	`docs/ADR-P2-201-XML-PARSER-SELECTION.md`, `reports/phase2-start-report.md`

Live Runtime Evidence

The docs-site is backed by real execution on Linux x64 with Node v24.18.0 and npm 11.16.0 after rebuilding the CLI from source. Evidence is recorded in reports/docs-site-live-evidence-2026-07-24.md and reports/docs-site-live-evidence-2026-07-24.json.

Runtime smoke

15/15 checks passed for version, help, safe generation, unsafe rejection, strip mode, optimizer directory use, and ESM import.

Formal tests

Pass for typecheck, lint budget, full test suite, security containment, safety matrix, and Phase 1 smoke contracts.

Measured efficiency

Measured optimizer size/time data is published in the command reference, with claims limited to reproducible local evidence.

Suite or command	Result	What it proves
`npm run typecheck`	Pass	TypeScript source integrity.
`npm run lint:budget`	Pass	0 errors, 14/14 approved warnings.
`npm run test`	Pass	Frameworks 11/11, config 10/10, E2E 8/8, integrations 7/7.
`npm run test:security`	Pass	27 containment assertions.
`npm run test:safety-matrix`	Pass	Reject, strip, and sandbox behavior across entry points.
`node scripts/benchmark-comprehensive.js`	Pass	Optimizer size/time behavior across repository samples.

Open full live evidence Open benchmark evidence

Quick Start

Install

npm install --save-dev svger-cli

Check the CLI

npx svger --version
npx svger --help

Build a directory

npx svger build ./src/icons ./src/components/icons \
  --framework react \
  --typescript \
  --optimize balanced

Generate one component

npx svger generate ./src/icons/logo.svg ./src/components/icons \
  --framework vue \
  --composition

The old documentation used convert and batch. The current executable command names are generate for one SVG and build for a source directory.

Complete CLI Surface

This is the compact command map. The full option-by-option reference, recipes, live smoke results, benchmark summary, and known limitations are documented in Commands and Live Evidence.

Command	Purpose	Important options
`build <src> <out>`	Build every discovered SVG from a source folder to an output folder.	`--framework`, `--typescript`, `--optimize`, `--recursive`, `--include`, `--exclude`, `--dry-run`, `--check`, `--diff`, `--format`
`generate <svgFile> <out>`	Convert one SVG file into one framework component.	`--framework`, `--typescript`, `--composition`, `--standalone`, `--optimize`
`watch <src> <out>`	Watch a source folder and rebuild components after file changes.	`--unsafe-input-policy`, `--max-input-size`
`optimize <input> [output]`	Optimize SVG files without generating components. Current runtime evidence verifies directory input/output.	`--level`, `--validate`, `--in-place`, `--unsafe-input-policy`
`config`	Create, show, update, and explain resolved configuration.	`--init`, `--show`, `--set key=value`, `--explain`, `--format json`
`plugins`	Load and list built-in or external plugins and show metrics.	`--load <names>`
`lock` / `unlock`	Protect source SVG files from accidental overwrite workflows.	Accept one or more file paths.
`clean <out>`	Remove generated SVG component output from a target directory.	`--out` remains as a deprecated alias.
`recover <directory>`	Inspect and roll back incomplete output transactions.	`--format pretty\|json`
`migrate <target> [path]`	Migrate v4 config, imports, or plugin declarations.	`--dry-run`, `--no-backup`, `--format json`

Framework Coverage

The implementation defines these framework targets in FrameworkType. Each target keeps source generation framework-idiomatic while preserving the same security and input gates.

React

TypeScript JSX, SVG props, forward-ref capable output.

React Native

React Native SVG component generation for mobile icon systems.

Vue 3

SFC output with Composition API and <script setup> support.

Angular

Standalone component support, OnPush-oriented configuration, optional signals flag.

Svelte

Svelte component output with TypeScript-capable templates.

Solid

Fine-grained JSX output for Solid projects.

Preact

Lightweight React-compatible component output.

Lit

Web component output for Lit and standards-based custom elements.

Vanilla

Plain JavaScript/TypeScript module output for non-framework stacks.

Build Tool and Test Integrations

Export path	Public API	Notes
`svger-cli/webpack`	`SvgerWebpackPlugin`, `svgerLoader`	Webpack 5 plugin and loader aliases.
`svger-cli/vite`	`svgerVitePlugin`	Vite plugin with HMR and virtual-module options.
`svger-cli/rollup`	`svgerRollupPlugin`	Rollup 4 plugin with generated output and source-map options.
`svger-cli/babel`	`svgerBabelPlugin`, `createBabelPlugin`	Babel 7 import transformation and initialization processing.
`svger-cli/nextjs`	`withSvger`, `SvgerNextJsPlugin`, `configureSvgImports`	Next.js 14-16 wrapper around the Webpack integration.
`svger-cli/jest`	`svgerJestTransformer`, `jestPreset`, `createJestTransformer`	Jest 29-30 SVG component transformer/preset.

Optimizer and Package Contents

Optimization levels

Component generation accepts none, basic, balanced, aggressive, and maximum. The standalone optimizer command defaults to balanced.

npx svger optimize ./icons --level maximum
npx svger build ./icons ./components --optimize aggressive

Published package shape

The v4.0.9 package candidate includes compiled runtime output, curated docs, examples, public binaries, policy files, and 606 intentional sample SVG assets. Internal reports, tests, coverage, source maps, and .github are excluded.

Security and Safety Controls

Input safety

Unsafe raw SVG content is rejected by default across CLI and integration entry points. The only permissive mode is explicit --unsafe-input-policy strip. A maximum input size can be set with --max-input-size.

Filesystem safety

Build output is sandboxed to the requested output directory. Phase 1 adds atomic writes, transaction recovery, deterministic reports, and cache fingerprinting for reproducible builds.

npx svger build ./icons ./components --unsafe-input-policy reject
npx svger build ./icons ./components --unsafe-input-policy strip --max-input-size 1048576
npx svger recover ./components --format json

Configuration

Configuration can come from defaults, .svgconfig.json, and CLI options. Use config explain to inspect origin and resolved values.

npx svger config --init
npx svger config --show
npx svger config --set framework=react
npx svger config explain --format json

Processing

watch, parallel, batchSize, maxConcurrency, cache, unsafeInputPolicy.

Output

source, output, outputConfig.naming, generated extension, output directory.

Frameworks

React, Vue, and Angular sub-configuration plus general framework options.

Programmatic API

The root package export exposes services, commands, compiler ports, diagnostics, reporting, configuration resolution, cache helpers, and integration factories. Type declarations are shipped with the package.

import {
  SVGProcessor,
  createSVGCompiler,
  BuildCommand,
  formatBuildReport,
  svgerVitePlugin,
  jestPreset
} from 'svger-cli';

Public subpath exports are available for Webpack, Vite, Rollup, Babel, Next.js, Jest, and package.json.

Support Matrix

Area	Supported or gated lines
Node.js	Production: Node 22 and 24 LTS. Forward smoke: Node 26 Current. Legacy smoke only: Node 18.17.
TypeScript	5.6.3 minimum compatibility, 5.9.3 primary, 7.0.2 current compatibility.
Bundlers	Webpack 5, Vite 6-8, Rollup 4, Babel 7, Next.js 14-16, Jest 29-30.
Release validation	Phase 0/Phase 1 validation scripts, package conformance, safety matrix, tarball consumer smoke.

Documentation Coverage Map

This page now covers the shipped implementation surface. The repository also keeps deeper source documents for framework details, integrations, support, migration, optional visual validation dependencies, governance, and release evidence.

README.md
docs-site/commands.html
docs/FRAMEWORK-GUIDE.md
docs/INTEGRATIONS.md
docs/OPTIONAL-DEPENDENCIES.md
docs/SUPPORT-MATRIX.md
docs/phase0-release-gate.md
docs/phase0-migration-notice.md
docs/phase0-rollback-plan.md
docs/ADR-P2-201-XML-PARSER-SELECTION.md
reports/package-conformance-v4.0.9.md
reports/docs-site-live-evidence-2026-07-24.md
reports/phase1-implementation-report.md
reports/phase2-start-report.md

Documentation review evidence for this update is recorded in reports/docs-site-review-2026-07-24.md and reports/docs-site-review-2026-07-24.json. Runtime evidence is recorded in reports/docs-site-live-evidence-2026-07-24.md and reports/docs-site-live-evidence-2026-07-24.json.