https://github.com/pivanov/vite-plugin-svg-sprite
https://github.com/pivanov/vite-plugin-svg-sprite
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/pivanov/vite-plugin-svg-sprite
- Owner: pivanov
- Created: 2024-09-28T21:37:20.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-01-06T01:39:03.000Z (4 months ago)
- Last Synced: 2025-04-12T07:53:19.995Z (about 1 month ago)
- Language: TypeScript
- Size: 27.3 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# @pivanov/vite-plugin-svg-sprite
A versatile and lightweight Vite plugin for generating SVG sprites from your SVG files, with support for HMR, SVGO optimization, and flexible configuration options.
## Features
- ⚡️ Fast SVG sprite generation
- 🔄 Hot Module Reloading (HMR) support
- 🎨 Preserves important SVG attributes (viewBox, fill, stroke)
- 🛠️ SVGO optimization built-in
- 📁 Multiple icon directory support
- 🔧 Configurable symbol IDs
- 💉 Optional HTML injection
- 📦 File output support
- 👀 Watch mode support
## Install
```bash
npm i -D @pivanov/vite-plugin-svg-sprite
# or
yarn add -D @pivanov/vite-plugin-svg-sprite
# or
pnpm add -D @pivanov/vite-plugin-svg-sprite
```
## Usage
Add the plugin to your `vite.config.ts` (or `vite.config.js`):
```typescript
import path from 'path';
import svgSpritePlugin from '@pivanov/vite-plugin-svg-sprite';
export default {
plugins: [
svgSpritePlugin({
iconDirs: [path.resolve(process.cwd(), 'src/assets/icons')],
symbolId: '[dir]-[name]',
svgDomId: 'svg-sprite',
inject: 'body-last',
}),
],
};
```
### Using SVG Sprites
You can use the generated sprites in two ways:
1. **Direct Import** (when not using inject option):
```typescript
import svgSpriteString from 'virtual:svg-sprite';
const container = document.createElement('div');
const shadow = container.attachShadow({ mode: 'open' });
const sprite = new DOMParser()
.parseFromString(svgSpriteString, 'image/svg+xml')
.documentElement;
shadow.appendChild(sprite);
document.body.appendChild(container);
```
2. **Reference in HTML** (works with both methods):
```html
```
## Configuration Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `iconDirs` | `string[]` | Required | Directories containing SVG files to be processed into sprites |
| `symbolId` | `string` | `[dir]-[name]` | Format for symbol IDs. Uses placeholders: `[dir]` (directory name) and `[name]` (file name without extension). Example: `[dir]-[name]` for `icons/home.svg` becomes `icons-home` |
| `svgDomId` | `string` | `svg-sprite` | ID attribute for the root SVG sprite element in the DOM |
| `inject` | `'body-last' \| 'body-first'` | `undefined` | Controls where the sprite is injected in the HTML. `body-first` injects at start of body, `body-last` at the end |
| `svgoConfig` | `object` | See SVGO section | Configuration for SVGO optimization. Override default settings for SVG optimization |
| `fileName` | `string` | `undefined` | If provided, saves the sprite to a file instead of injecting it. Example: `sprite.svg` |
| `verbose` | `boolean` | `true` | Enable/disable detailed logging output during plugin operation |
### Default SVGO Configuration
The plugin comes with optimized SVGO defaults:
```typescript
{
plugins: [
{
name: 'preset-default',
params: {
overrides: {
removeViewBox: false,
removeUnknownsAndDefaults: {
defaultAttrs: false,
},
cleanupIds: {
minify: false,
},
mergePaths: false,
},
},
},
{
name: 'removeAttributesBySelector',
params: {
selectors: [
{
selector: '*:not(svg)',
preserve: ['stroke*', 'fill*'],
},
],
},
},
],
}
```
## Examples
### Basic Usage with HTML Injection
```typescript
svgSpritePlugin({
iconDirs: ['src/icons'],
symbolId: 'icon-[name]',
inject: 'body-last'
})
```
### File Output Without Injection
```typescript
svgSpritePlugin({
iconDirs: ['src/icons'],
symbolId: 'icon-[name]',
fileName: 'sprite.svg'
})
```
### With Custom SVGO Config
```typescript
svgSpritePlugin({
iconDirs: ['src/icons'],
symbolId: 'icon-[name]',
svgoConfig: {
plugins: [
{
name: 'removeAttrs',
params: { attrs: '(fill|stroke)' }
}
]
}
})
```
## Generated Sprite Example
The plugin generates a sprite that looks like this:
```html
```
## Author
Created by [pivanov](https://github.com/pivanov)
## License
MIT