@ssvg/vite-plugin

A Vite plugin for seamless integration of sSVG files into your development workflow. Automatically compiles .ssvg files to .svg during development and processes inline <ssvg> blocks in HTML.

Note: If you're working in a React project, you may want to use our React component instead: @ssvg/react

Installation

npm install --save-dev @ssvg/vite-plugin

Requires Vite 4 or 5. The plugin includes @ssvg/core as a dependency.

Compatibility Note: This plugin now supports Vite versions 4, 5, 6, and 7. If you use an even newer version, please report any issues.

Usage

Basic Setup

Add the plugin to your vite.config.ts:

import { defineConfig } from 'vite';
import ssvgPlugin from '@ssvg/vite-plugin';

export default defineConfig({
  plugins: [
    ssvgPlugin(),
  ],
});

Options

ssvgPlugin({
  skipUnderscoreFiles: true, // Default: true - skips files starting with '_'
});

How It Works

• Development Mode: Watches for .ssvg files and compiles them to .svg on save. Also transforms <ssvg> tags in HTML to <svg>.
• Build Mode: No transformation of .ssvg files (they remain as-is), but <ssvg> blocks in HTML are transformed to <svg>. Focused on dev workflow for file watching.

File Structure

Place .ssvg files anywhere in your project. The plugin will create corresponding .svg files:

project/
├── src/
│   ├── logo.ssvg    # → compiles to logo.svg
│   └── index.html   # can contain <ssvg> blocks
└── vite.config.ts

Inline Usage

Use <ssvg> tags in your HTML for inline graphics:

<ssvg>
  <!-- your ssvg content here -->
</ssvg>

Troubleshooting

Plugin Not Loading

• Ensure Vite config is correct and plugin is added to plugins array
• Check for import errors in console

Files Not Compiling

• Verify you're running npm run dev (not build)
• Check file paths and extensions
• Ensure @ssvg/core is installed

TypeScript Issues

Add to your types file:

declare module '@ssvg/vite-plugin' {
  import type { Plugin } from 'vite';
  export default function ssvgPlugin(options?: { skipUnderscoreFiles?: boolean }): Plugin;
}

Errors from @ssvg/core

• The plugin handles core compilation errors
• Check Vite console for warnings
• Ensure your .ssvg files are valid (see sSVG docs)

API

ssvgPlugin(options?)

• options.skipUnderscoreFiles (boolean): Skip files starting with _. Default: true

Returns a Vite plugin.

License

MIT © SSVG