Runtime checked against source v4.0.9

Node v24.18.0

npm 11.16.0

Complete commands, system capabilities, and live runtime proof.

This page documents the actual CLI surface, supported frameworks, integrations, safety controls, configuration features, package behavior, and live validation evidence for SVGER-CLI v4.0.9. It is intentionally more factual than marketing: performance and accuracy statements are tied to commands, tests, and measured outputs.

View live test evidence Optimizer guide Browser benchmark demo Repository

Installation and executable names

Install

npm install --save-dev svger-cli

Executables

The package exposes these binaries:

svger svger-cli test-svger

npx svger --version
npx svger --help
npx svger build --help
npx svger generate --help
npx svger optimize --help

Complete command reference

Commands below are taken from the current CLI help and source. Deprecated aliases are listed so migrations remain explicit, but new docs should teach positional arguments and current command names.

Command	Use it for	Syntax and options
`build`	Build every discovered SVG in a source directory into generated components.	`svger build <src> <out>` Options: `--framework`, `--typescript`, `--no-typescript`, `--composition`, `--standalone`, `--signals`, `--optimize`, `--validate`, `--plugin`, `--list-plugins`, `--unsafe-input-policy`, `--max-input-size`, `--recursive`, `--include`, `--exclude`, `--hidden`, `--symlinks`, `--max-file-count`, `--collision`, `--concurrency`, `--batch-size`, `--dry-run`, `--check`, `--diff`, `--format`. Deprecated aliases: `--src`, `--out`, `--naming`.
`generate`	Generate one component from one SVG file.	`svger generate <svgFile> <out>` Options: `--framework`, `--typescript`, `--no-typescript`, `--composition`, `--standalone`, `--optimize`, `--unsafe-input-policy`, `--max-input-size`.
`watch`	Watch a source directory and rebuild after SVG changes.	`svger watch <src> <out>` Options: `--unsafe-input-policy`, `--max-input-size`. Deprecated compatibility options: `--src`, `--out`, `--watch`.
`optimize`	Optimize SVG files without generating components.	`svger optimize <inputDir> [outputDir]` Options: `--level`, `--validate`, `--in-place`, `--unsafe-input-policy`, `--max-input-size`. Current runtime behavior is directory-oriented; see the known limitation section.
`config`	Create, show, update, and explain resolved configuration.	`svger config [action] [path]` Options: `--init`, `--set key=value`, `--show`, `--explain`, `--format pretty\|json`.
`plugins`	List plugin registrations and load plugin names or paths.	`svger plugins --load optimize,minify`
`lock`	Lock one or more SVG files before workflows that must not overwrite them.	`svger lock ./icons/logo.svg ./icons/menu.svg`
`unlock`	Unlock one or more previously locked SVG files.	`svger unlock ./icons/logo.svg ./icons/menu.svg`
`clean`	Remove generated component output from the target directory.	`svger clean <out>`. Deprecated alias: `--out`.
`recover`	Inspect and roll back incomplete output transactions.	`svger recover <directory> --format pretty\|json`
`migrate`	Migrate v4 config, imports, or plugin declarations.	`svger migrate <target> [path]` Options: `--dry-run`, `--no-backup`, `--format json`.

Common instructions and recipes

React TypeScript icon folder

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

Vue Composition API component

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

Angular standalone output

npx svger build ./icons ./angular-icons \
  --framework angular \
  --standalone \
  --signals

Safe optimizer directory run

npx svger optimize ./icons ./optimized-icons --level maximum

Reject unsafe SVG by default

npx svger generate ./unsafe.svg ./components --framework react

Explicit strip mode

npx svger generate ./unsafe.svg ./components \
  --framework react \
  --unsafe-input-policy strip

Dry-run/check mode

npx svger build ./icons ./components --dry-run --format json
npx svger build ./icons ./components --check --diff

Configuration explanation

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

System capabilities

Framework targets

React, React Native, Vue, Angular, Svelte, Solid, Preact, Lit, and vanilla output. Runtime framework validation generated 11 representative component variants.

Build integrations

Webpack, Vite, Rollup, Babel, Next.js, and Jest exports are available and verified by integration construction tests.

Optimization

Optimization levels: none, basic, balanced, aggressive, and maximum. The standalone optimizer command currently operates on directories.

Safety

Reject-by-default unsafe SVG containment, explicit strip mode, input-size limits, and artifact-path sandboxing across CLI and integration entry points.

Reproducibility

Phase 1 evidence covers deterministic planning, build reports, atomic writes, recovery, cache contracts, migration contracts, and traceability.

Programmatic API

Root exports include processors, compiler factories, commands, reports, diagnostics, services, cache helpers, and integration factories with TypeScript declarations.

Framework output evidence

Framework test path	Generated file	Status
React	`TestIcon-react.tsx`	Pass
React Native	`TestIcon-react-native.tsx`	Pass
Vue Composition API	`TestIcon-vue-composition.vue`	Pass
Vue Options API	`TestIcon-vue-options.vue`	Pass
Svelte	`TestIcon-svelte.svelte`	Pass
Angular standalone	`TestIcon-angular-standalone.component.ts`	Pass
Angular module	`TestIcon-angular-module.component.ts`	Pass
Solid	`TestIcon-solid.tsx`	Pass
Preact	`TestIcon-preact.tsx`	Pass
Lit	`TestIcon-lit.ts`	Pass
Vanilla	`TestIcon-vanilla.ts`	Pass

Integration export evidence

Integration	Export path	Verified capability
Webpack	`svger-cli/webpack`	Plugin instance and loader function available.
Vite	`svger-cli/vite`	Plugin created with name `svger-vite-plugin`.
Rollup	`svger-cli/rollup`	Plugin created with name `svger-rollup-plugin`.
Babel	`svger-cli/babel`	Plugin and factory function available.
Next.js	`svger-cli/nextjs`	`withSvger` wrapper and standalone plugin available.
Jest	`svger-cli/jest`	Transformer and preset config available.
Main exports	`svger-cli`	Integration factories are exposed from the root package.

Live runtime evidence

These checks were executed locally after rebuilding the CLI from source. They prove the documented commands operate in a real runtime environment.

Smoke

15/15 runtime assertions passed.

Frameworks

11/11 framework component outputs generated.

Integrations

7/7 integration export checks passed.

Evidence item	Runtime command or suite	Result
Version identity	`npx svger --version`	Returned `4.0.9`.
Help discovery	`npx svger --help` and command help screens	All command groups and help screens available.
Safe single generate	`npx svger generate ./icons/safe.svg ./components --framework react --typescript`	Generated `Safe.tsx`.
Safe directory build	`npx svger build ./icons ./build-components --framework vue --typescript --optimize balanced`	Generated `Safe.vue`.
Unsafe rejection	`<script>`, `on*`, and `javascript:` SVG inputs	Rejected with nonzero exits.
Explicit strip policy	`--unsafe-input-policy strip`	Generated output and emitted a security warning.
Input-size limit	`--max-input-size 256`	Oversized input rejected.
Optimizer	`npx svger optimize ./icons ./optimized --level maximum`	Optimized directory output and reduced smoke sample size by 12.72%.
Optimizer unsafe exit	`npx svger optimize ./unsafe-icons ./optimized-unsafe`	Exited nonzero for unsafe input.
Programmatic API	ESM import of `SVGProcessor` and `createSVGCompiler`	Import succeeded.

Accuracy and quality proof

Accuracy is documented as test-backed behavior: generated components are syntactically valid for the target frameworks, configuration and E2E workflows pass, unsafe input is rejected, and API/integration contracts remain importable.

Validation command	Result	Capability proven
`npm run typecheck`	Pass	TypeScript source type integrity.
`npm run lint:budget`	Pass	0 errors; warning count remains at approved 14/14 baseline.
`npm run test`	Pass	Frameworks, configuration, E2E flows, integrations.
`npm run test:security`	Pass	27 containment assertions.
`npm run test:safety-matrix`	Pass	Reject, strip, and sandbox behavior across entry points.
`npm run test:phase1:smoke`	Pass	Report, application service, and transaction recovery contracts.

Efficiency and benchmark evidence

Efficiency claims on this site are limited to measured data. The local optimizer benchmark was run with node scripts/benchmark-comprehensive.js after the production build.

Optimization level	Average size reduction	Average processing time	Average memory
BASIC	6.26%	0.51ms	47.69KB
BALANCED	7.76%	1.46ms	158.67KB
AGGRESSIVE	6.86%	5.07ms	110.52KB
MAXIMUM	11.75%	3.22ms	346.21KB

The benchmark script's visual column is not treated as authoritative proof because the script falls back to zero if optional visual comparison fails. Use the visual validation test commands in the repository when optional visual dependencies are installed.

Known limitations and governance status

Area	Status	Documentation position
npm release	Pending	Source is v4.0.9; npm publication and independent registry verification still need to close the official gate.
Single-file optimize	Known current behavior	Runtime evidence shows `svger optimize ./file.svg ./out` exits with `ENOTDIR`. Use directory input/output until this is fixed or officially reclassified.
Phase 2 parser implementation	Blocked	P2-201 ADR work is permitted; production parser adapter work remains blocked by governance gates.
Compatibility ledger rows	Approval-gated	Rows must be approved before dependent behavior changes are merged or declared canonical.