npm package: @getkist/action-svg
Description: SVG processing actions for kist - sprite generation, optimization, and PNG conversion
Author: kist
Latest version: 1.0.9

# @getkist/action-svg

SVG processing actions for [kist](https://github.com/getkist/kist) build tool.

[![npm version](https://img.shields.io/npm/v/@getkist/action-svg.svg)](https://www.npmjs.com/package/@getkist/action-svg)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 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

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

## Usage

### Basic Sprite Generation

Add to your `kist.yml`:

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

### Custom Configuration

```yaml
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

```typescript
{
  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:

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

### Stack Mode

Creates stackable SVG sprite for CSS targeting:

```yaml
config:
    mode:
        stack:
            sprite: stack.svg
```

### CSS Mode

Generates CSS classes for background images:

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

### View Mode

Creates individual views for each icon:

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

## Examples

### Multiple Sprites

Generate different sprites for different icon sets:

```yaml
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

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

### Optimized for Production

```yaml
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

```typescript
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:

```typescript
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](CONTRIBUTING.md).

## License

MIT © kist

## Resources

- [kist Documentation](https://github.com/getkist/kist)
- [svg-sprite Documentation](https://github.com/svg-sprite/svg-sprite)
- [SVGO Documentation](https://github.com/svg/svgo)
- [Plugin Development Guide](https://github.com/getkist/kist/blob/main/PLUGIN_DEVELOPMENT.md)

## Support

- Issues: [GitHub Issues](https://github.com/getkist/kist-action-svg/issues)
- Discussions: [kist Discussions](https://github.com/getkist/kist/discussions)