@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

Action: SvgReaderAction

Reads SVG file contents into memory, making them available to later pipeline steps or via getSvgContent() for programmatic use.

Usage

pipeline:
    stages:
        - name: assets
          steps:
              - name: read-svg
                action: SvgReaderAction
                options:
                    filePath: ./assets/logo.svg

Options

| Option | Type | Required | Description | | ---------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | filePath | string | Yes | Path to the SVG file to read. Resolved relative to the current working directory via path.resolve, so both relative and absolute paths work. |

The content read is cached on the action instance; each call to execute replaces the cached content rather than appending to it.

Action: SvgPackagerAction

Optimizes SVG files with SVGO and packages them into optimized SVGs, TypeScript modules, and a JSON index.

Usage

pipeline:
    stages:
        - name: assets
          steps:
              - name: package-icons
                action: SvgPackagerAction
                options:
                    inputDirectory: ./src/icons
                    outputDirectory: ./dist/icons
                    tsOutputDirectory: ./dist/ts
                    jsonOutputDirectory: ./dist

Options

| Option | Type | Required | Description | | --------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------- | | svgoConfigPath | string | No | Path to the SVGO configuration file (default: ./config/svgo.config.js) | | inputDirectory | string | No | Directory to recursively search for *.svg files (default: src/icons) | | outputDirectory | string | No | Output directory for the optimized .svg files, one per input icon (default: dist/icons) | | tsOutputDirectory | string | No | Output directory for generated .ts files, each exporting an icon_<name> string constant (default: dist/ts) | | jsonOutputDirectory | string | No | Output directory for the generated icons.json index of processed icon names (default: dist) |

All options are optional and default to conventional src/dist locations. If no SVG files are found in inputDirectory, the action logs a warning and returns without writing any output.

Action: SvgToPngAction

Converts raw SVG markup to a PNG file, using canvg for rendering and node-canvas for encoding.

Usage

pipeline:
    stages:
        - name: assets
          steps:
              - name: convert-to-png
                action: SvgToPngAction
                options:
                    svgContent: "<svg>...</svg>"
                    outputPath: ./dist/logo.png
                    width: 512
                    height: 512

Options

| Option | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------- | | svgContent | string | Yes | Raw SVG markup to convert (not a file path). Pair with SvgReaderAction to convert a file on disk. | | outputPath | string | Yes | Filesystem path where the PNG file will be written. Parent directories are created automatically. | | width | number | No | Output width in pixels (default: the SVG's own width attribute if present, otherwise 800) | | height | number | No | Output height in pixels (default: the SVG's own height attribute if present, otherwise 600) |

Requirements

• Node.js >= 22.0.0
• kist >= 0.1.58

Dependencies

• svg-sprite - Sprite generation engine
• svgo - SVG optimization
• canvas - Powers SvgToPngAction, providing the canvas used to render and encode PNG output
• canvg - Powers SvgToPngAction, rendering SVG markup onto the canvas

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