@getkist/action-svg

SVG processing actions for kist build tool.

Features

• SVG Sprite Generation - Combine multiple SVG files into optimized sprite sheets
• Multiple Sprite Modes - Symbol, stack, CSS, view, and defs modes
• Automatic Optimization - Built-in SVGO integration
• CSS Generation - Automatic stylesheet generation for sprites
• Highly Configurable - Customize sprite generation with svg-sprite options

Installation

npm install --save-dev @getkist/action-svg

Usage

Basic Sprite Generation

Add to your kist.yml:

pipeline:
    stages:
        - name: assets
          steps:
              - name: generate-icon-sprite
                action: SvgSpriteAction
                options:
                    sourceDir: ./src/icons
                    outputDir: ./dist/sprites

Custom Configuration

pipeline:
    stages:
        - name: assets
          steps:
              - name: custom-sprite
                action: SvgSpriteAction
                options:
                    sourceDir: ./assets/svg
                    outputDir: ./public/sprites
                    config:
                        mode:
                            symbol:
                                sprite: custom-sprite.svg
                                inline: true
                            css:
                                render:
                                    css: true
                                    scss: true

Action: SvgSpriteAction

Compiles multiple SVG files into sprite sheets with various output modes.

Options

| Option | Type | Required | Description | | ----------- | ------ | -------- | ------------------------------------- | | sourceDir | string | Yes | Directory containing source SVG files | | outputDir | string | Yes | Directory for generated sprite files | | config | object | No | Custom svg-sprite configuration |

Default Configuration

{
  dest: "./dist/sprite",
  shape: {
    id: {
      separator: "--",
      generator: "icon-%s",
      pseudo: "~"
    },
    dimension: {
      maxWidth: 2000,
      maxHeight: 2000,
      precision: 2,
      attributes: false
    },
    spacing: {
      padding: 0,
      box: "content"
    },
    transform: ["svgo"]
  },
  svg: {
    xmlDeclaration: false,
    doctypeDeclaration: true,
    namespaceIDs: true,
    namespaceClassnames: false,
    dimensionAttributes: true
  },
  mode: {
    css: {
      render: {
        css: true
      }
    },
    view: true,
    defs: true,
    symbol: {
      sprite: "icon.sprite.svg"
    },
    stack: true
  }
}

Sprite Modes

Symbol Mode

Creates a sprite with <symbol> elements, ideal for inline SVG usage:

config:
    mode:
        symbol:
            sprite: icons.svg
            inline: true

Stack Mode

Creates stackable SVG sprite for CSS targeting:

config:
    mode:
        stack:
            sprite: stack.svg

CSS Mode

Generates CSS classes for background images:

config:
    mode:
        css:
            render:
                css: true
                scss: true
            sprite: sprite.svg

View Mode

Creates individual views for each icon:

config:
    mode:
        view:
            bust: false
            render:
                css: true

Examples

Multiple Sprites

Generate different sprites for different icon sets:

steps:
    - name: ui-icons
      action: SvgSpriteAction
      options:
          sourceDir: ./src/icons/ui
          outputDir: ./dist/sprites
          config:
              mode:
                  symbol:
                      sprite: ui-icons.svg

    - name: social-icons
      action: SvgSpriteAction
      options:
          sourceDir: ./src/icons/social
          outputDir: ./dist/sprites
          config:
              mode:
                  symbol:
                      sprite: social-icons.svg

With Custom ID Generator

steps:
    - name: custom-ids
      action: SvgSpriteAction
      options:
          sourceDir: ./icons
          outputDir: ./dist
          config:
              shape:
                  id:
                      generator: "custom-icon-%s"
                      separator: "__"

Optimized for Production

steps:
    - name: production-sprite
      action: SvgSpriteAction
      options:
          sourceDir: ./src/icons
          outputDir: ./dist/assets
          config:
              shape:
                  transform:
                      - svgo:
                            multipass: true
                            plugins:
                                - removeTitle
                                - removeDesc
                                - removeViewBox: false
              mode:
                  symbol:
                      sprite: icons.min.svg
                      inline: false

Programmatic Usage

import { SvgSpriteAction } from "@getkist/action-svg";

const action = new SvgSpriteAction({
    mode: {
        symbol: {
            sprite: "custom.svg",
        },
    },
});

await action.execute({
    sourceDir: "./icons",
    outputDir: "./dist/sprites",
});

TypeScript Support

Full TypeScript support with type definitions:

import { SvgSpriteAction, SvgSpriteActionOptions } from "@getkist/action-svg";

const options: SvgSpriteActionOptions = {
    sourceDir: "./icons",
    outputDir: "./dist",
    config: {
        mode: {
            symbol: true,
        },
    },
};

Output Structure

The action generates multiple files based on configured modes:

dist/sprites/
├── symbol/
│   └── sprite.svg          # Symbol sprite
├── stack/
│   └── sprite.svg          # Stack sprite
├── css/
│   ├── sprite.svg          # CSS sprite
│   └── sprite.css          # Generated CSS
├── view/
│   ├── icon1.svg          # Individual views
│   └── icon2.svg
└── defs/
    └── sprite.svg          # Defs sprite

Requirements

• Node.js >= 18.0.0
• kist >= 0.1.0

Dependencies

• svg-sprite - Sprite generation engine
• svgo - SVG optimization
• canvas - For PNG conversion (future)
• canvg - SVG to canvas rendering (future)

Contributing

Contributions welcome! Please read the contributing guidelines.

License

MIT © kist

Resources

• kist Documentation
• svg-sprite Documentation
• SVGO Documentation
• Plugin Development Guide

Support

• Issues: GitHub Issues
• Discussions: kist Discussions