svg-sprite-forge

A lightweight, efficient CLI tool to generate SVG sprite files and TypeScript definitions from your SVG icon collections.

Features

• 🚀 Fast Processing: Utilizes fast-glob for efficient file handling
• 🧹 Optimization: Automatically optimizes SVGs with SVGO
• 🎨 Customizable: Configure prefixes, colors, and more
• 📝 TypeScript Support: Generates TypeScript definition files for your icons
• 🔄 Modern: Built with modern JavaScript and TypeScript

Installation

# Using npm
npm install svg-sprite-forge --save-dev

# Using yarn
yarn add svg-sprite-forge --dev

# Using pnpm
pnpm add svg-sprite-forge --save-dev

Usage

Basic Usage

npx svg-sprite-forge

This will use the default options to:

1. Look for SVG files in an ./icons directory
2. Generate a sprite file at ./sprite.svg
3. Generate TypeScript definitions at ./icons.d.ts

Custom Options

npx svg-sprite-forge --input=src/assets/icons --output=public/sprite.svg --types=src/types/icons.d.ts --prefix=my-icon-

NPM Scripts

Add to your package.json:

{
  "scripts": {
    "build:icons": "svg-sprite-forge --input=src/icons --output=public/assets/sprite.svg"
  }
}

Then run:

npm run build:icons

Options

| Option | Default | Description | | ------------------- | -------------- | ------------------------------------------------------------ | | -v, --version | - | Display version information and exit | | -h, --help | - | Display help message and exit | | --input | ./icons | Directory containing SVG files | | --output | ./sprite.svg | Output path for the generated sprite | | --types | ./icons.d.ts | Output path for TypeScript definitions or 'false' to disable | | --prefix | icon- | Prefix for icon IDs in the sprite | | --no-strip-colors | false | Don't convert SVG colors to currentColor | | --no-optimize | false | Don't optimize SVGs with SVGO |

How It Works

svg-sprite-forge takes your individual SVG files and combines them into a single SVG sprite file. This approach enables:

1. Reduced HTTP Requests: Load a single file instead of multiple SVGs
2. Efficient Caching: Browser caches one file for all icons
3. Easy Styling: By default, icons use currentColor for easy CSS styling

The generated sprite looks like:

<svg
  xmlns="http://www.w3.org/2000/svg"
  aria-hidden="true"
  style="width: 0; height: 0; position: absolute;"
  viewBox="0 0 16 16"
>
  <defs>
    <symbol id="icon-arrow"><!-- SVG content --></symbol>
    <symbol id="icon-close"><!-- SVG content --></symbol>
    <!-- More symbols -->
  </defs>
</svg>

Same-Origin Requirement

Important: SVG sprites must be served from the same domain as your website. Due to security restrictions in most browsers, the <use> element with xlink:href cannot reference external SVG sprites across different domains or CDNs. This cross-origin restriction (CORS) prevents potential security vulnerabilities. If you need to serve your sprite from a CDN, you'll need to ensure proper CORS headers are set, though even this might not work in all browsers. For best compatibility, host the sprite file on the same domain as your website.

Using the Generated Sprite

HTML

When you run svg-sprite-forge, it generates a sprite file that you need to include in your project. For optimal performance and to take advantage of browser caching, reference the external sprite file:

<svg width="24" height="24" aria-hidden="true">
  <use xlink:href="sprite.svg#icon-arrow"></use>
</svg>

Make sure to place the generated sprite.svg file in a location that's accessible to your web pages, and maintain the correct path in your references.

React

import type { SVGProps } from "react";
import ReactDOM from "react-dom";

import sprite from "./path/to/sprite.svg";

type Props = {
  name: IconName; // type safe icon name through generated types
  size?: number;
} & SVGProps<SVGSVGElement>;

const spritePath = (sprite as { src: string }).src;

export function Icon({ name, size = 20, ...props }: Props) {
  ReactDOM.preload(spritePath, {
    as: "image",
  });

  return (
    <svg
      xmlns="http://www.w3.org/2000/svg"
      width={size}
      height={size}
      aria-hidden="true"
      {...props}
    >
      <use xlinkHref={`${spritePath}#icon-${name}`} />
    </svg>
  );
}

Best Practices

1. Consistent Viewbox: Ensure your SVGs have a consistent viewBox for predictable sizing
2. Clean SVGs: Remove unnecessary elements and attributes from source files
3. Build Integration: Add icon generation to your build process
4. Naming Convention: Use a consistent naming pattern for your SVG files

License

This project is licensed under the ISC License - see the LICENSE file for details.