SVG Sprite Command Line Interface

2.0.1 · active · verified Wed Apr 22

svg2sprite-cli provides a command-line interface for the `svg2sprite` library, designed to generate SVG sprites from a collection of individual SVG files. The current stable version is 2.0.1, though the underlying `svg2sprite` library, which `svg2sprite-cli` wraps, has not seen significant updates in approximately 9 years. The package itself has a very slow release cadence, with major version updates typically reflecting updates to its core dependency rather than new features in the CLI layer. Its key differentiator is providing a straightforward, opinionated command-line utility for SVG sprite generation, avoiding the need for direct programmatic integration of `svg2sprite` into a build system.

Common errors

```
command not found: svg2sprite
```
cause The `svg2sprite-cli` package was not installed globally, or the global `node_modules` bin directory is not in your system's PATH.

fix Install the package globally using `npm i -g svg2sprite-cli` or `yarn global add svg2sprite-cli`. Ensure your system's PATH includes the directory where global npm/yarn executables are installed (e.g., `/usr/local/bin` or `$HOME/.npm-global/bin`).
```
Error: The source directory does not exist.
```
cause The provided source directory path (`<source-directory>`) either does not exist, is misspelled, or is not accessible from the current working directory.

fix Verify the source directory path is correct and exists. Use an absolute path or a path relative to where you are running the `svg2sprite` command. Example: `svg2sprite ./src/icons ./dist/sprite.svg`.

Warnings

breaking The update to `svg2sprite@2.0.0` in `svg2sprite-cli@2.0.0` indicates potential breaking changes in the underlying sprite generation logic or output format. While the CLI's command-line interface might remain compatible, the generated SVG sprite's structure, attributes, or behavior could have changed due to the major version bump of its core dependency.
Fix: Review the changelog of the `svg2sprite` library (not `svg-sprite`) for specific changes if migrating from `svg2sprite-cli@1.x`. Test generated sprites thoroughly for compatibility with your existing CSS/HTML usage.
gotcha When specifying multiple attributes to remove using `--stripAttrs`, the flag must be repeated for each attribute. Providing a comma-separated list or multiple values to a single `--stripAttrs` instance will not work as expected.
Fix: Correct: `svg2sprite ... --stripAttrs id --stripAttrs viewBox`. Incorrect: `svg2sprite ... --stripAttrs id,viewBox`.
gotcha Glob patterns used with options like `--ignore` might be interpreted by the shell before being passed to `svg2sprite-cli`. This can lead to unexpected behavior if the shell expands the glob, especially with complex patterns like `**`.
Fix: Always wrap glob patterns in single quotes (e.g., `--ignore '*.svg'` or `--ignore 'icons/**/*.svg'`) to ensure they are passed literally to the CLI for proper interpretation.

Install

npm install svg2sprite-cli npm
yarn add svg2sprite-cli yarn
pnpm add svg2sprite-cli pnpm

Imports

svg2sprite
wrong:
```
import { svg2sprite } from 'svg2sprite-cli'
```
correct:
```
$ npm i -g svg2sprite-cli
```
This package is a CLI tool and is primarily used via its globally installed `svg2sprite` command. It does not export modules for programmatic JavaScript/TypeScript import.
Usage
wrong:
```
$ node svg2sprite-cli <source-directory> <dist-file>
```
correct:
```
$ svg2sprite <source-directory> <dist-file> [options]
```
The `svg2sprite` command should be run directly after global installation, not via `node` on the package executable.
Options
```
$ svg2sprite images/svg out/sprite.svg --iconPrefix=prefix --ignore 'rainbow.svg'
```
Command-line options are prefixed with `--` or `-`. Glob patterns for `--ignore` may require single quotes in some shell environments to prevent shell expansion.

Quickstart

Demonstrates global installation, creation of dummy SVG source files, and generating an SVG sprite with options for ignoring files and applying an icon prefix, then displaying its content.

# Install the CLI globally
npm i -g svg2sprite-cli

# Create a directory for your SVG icons
mkdir -p src/icons

# Create some dummy SVG files (replace with your actual icons)
echo '<svg viewBox="0 0 24 24"><path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-2 15l-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8l-9 9z"/></svg>' > src/icons/check.svg
echo '<svg viewBox="0 0 24 24"><path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-1 15h2v-6h-2v6zm0-8h2V7h-2v2z"/></svg>' > src/icons/info.svg

# Create an output directory
mkdir -p dist

# Generate the SVG sprite, ignoring one icon and adding a prefix
# The output will be in dist/sprite.svg
svg2sprite src/icons dist/sprite.svg --ignore 'info.svg' --iconPrefix='my-icon-'

# You can verify the generated sprite content
cat dist/sprite.svg

# Example of how to use the sprite in HTML (conceptual):
# <svg><use xlink:href="/dist/sprite.svg#my-icon-check"></use></svg>

view raw JSON →