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.
Install globally to use svgforge anywhere:
npm install --global @svgforge/svgforge-cliOr as a project dependency (e.g. for usage in npm scripts):
npm install --save-dev @svgforge/svgforge-clisvgforge [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.
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/*.svgCreate a symbol sprite with an accompanying CSS stylesheet and example document:
svgforge --symbol --symbol-render-css --symbol-example --dest=out assets/*.svgAdd a 10px padding around all shapes of a stack sprite:
svgforge --stack -p 10 assets/*.svgInstead of passing options on the command line you can also use an external JSON config file:
svgforge --config config.json assets/*.svgTip: A config file can be generated with AI DeepWiki online configurator.
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) |
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).
Requirements: Node.js >= 18, 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.
- svgforge — the underlying sprite creation library
- svgforge docs — detailed documentation of all sprite modes
MIT © svgforge