@svgforge/svgforge-cli

Command line interface for svgforge — create optimized SVG sprites of several types along with accompanying stylesheet resources and example documents.

The configuration options are documented in the svgforge library.

There is a Github page with some tutorials.

Installation

Install globally to use svgforge anywhere:

npm install --global @svgforge/svgforge-cli

Or as a project dependency (e.g. for usage in npm scripts):

npm install --save-dev @svgforge/svgforge-cli

Usage

svgforge [options] files

Run svgforge --help to get a full list of all available options, or consult the command line reference.

After each run the CLI prints a compact summary to stderr: processed shapes, active modes, written files and elapsed time. It also reports whether the @resvg/resvg-js dimension fallback — only used for the unusual case of SVGs without a viewBox or width/height — is installed:

shapes    42 processed
modes     view (example: yes)
resvg     available
output    3 files → out
elapsed   0.51s (concurrency 4)

Skipped shapes — files that could not be processed, e.g. invalid SVG/XML, or SVGs without a determinable size when the fallback is missing — never end up in the sprite. Every skip is printed immediately as Skipping "<file>" (<reason>) and counted on an extra summary line:

shapes    3 processed
skipped   1 (1 failed)
modes     symbol (inline: no, example: no)

When the @resvg/resvg-js package is missing and the fallback is needed for an SVG without a viewBox or width/height, such a shape is skipped as well: the summary shows resvg not installed, the skip is counted as without dimensions, no invalid NaN viewBox values are produced, and the summary ends with the recommendation npm install @resvg/resvg-js to enable the fallback.

Examples

Create a view sprite of all SVG files in assets/ and write the result — along with an example HTML document — to the out/ directory:

svgforge --view --view-example --view-bust=false --dest=out assets/*.svg

Create a symbol sprite with an accompanying CSS stylesheet and example document:

svgforge --symbol --symbol-render-css --symbol-example --dest=out assets/*.svg

Add a 10px padding around all shapes of a stack sprite:

svgforge --stack -p 10 assets/*.svg

Instead of passing options on the command line you can also use an external JSON config file:

svgforge --config config.json assets/*.svg

Tip: A config file can be generated with AI DeepWiki online configurator.

Sprite modes

The CLI supports all four sprite modes of svgforge. Activate them individually or combine them in a single run (e.g. --view --symbol):

| Mode | Flag | Description | | ---- | ---- | ----------- | | view | --view / -v | SVG view-based sprite | | symbol | --symbol / -s | Sprite of <symbol> elements for inline embedding | | stack | --stack / -S | Stacked sprite with :target CSS | | defs | --defs / -d | Sprite of <defs> elements (legacy) |

Advanced globbing

Some shells don't support the double-star character **. Wrap your glob expression in single quotes so that Node.js handles the matching instead:

svgforge --config config.json 'assets/**/*.svg'

The CLI typically derives shape IDs from the file basename. To start ID traversal from a base directory, add a symbolic link to that directory (./) to your pattern:

svgforge --config config.json 'assets/./**/*.svg'

This results in shape IDs like path--to--source (assuming the default shape ID generator is used).

Development

Requirements: Node.js >= 24, pnpm.

pnpm install
pnpm lint     # Run XO linter
pnpm test     # Run the test suite (node --test)

The test suite spawns the CLI as a child process against fixtures in test/fixtures/ and asserts the generated sprite files and their contents.

Related

• svgforge — the underlying sprite creation library
• svgforge docs — detailed documentation of all sprite modes

License

MIT © svgforge