vite-plugin-svg-spritemap

This plugin supports Vite 4 and 5.

This ViteJS plugin generates a single SVG spritemap with <symbol>/<view>/<use> for each SVG files. It can also generate a stylesheet (CSS/SCSS/Stylus/Less) containing the sprites to be used directly (via a Data URI or SVG fragments).

The plugin outputs can be fully configurable through options.

This plugin is inspired by svg-spritemap-webpack-plugin for Webpack.

🚀 Features

• ⚡ Fully integrated in your ViteJS environment
• 📦 Pack your SVG files in one (spritemap) file
• ✨ Use your SVG in an <svg> or <img> tags and also directly in your CSS/SCSS/Stylus/Less
• 🍕 Import SVG fragment as VueJS component
• 🔥 HMR support

📦 Install

1npm i -D @twir/vite-plugin-svg-spritemap
2
3# yarn
4yarn add -D @twir/vite-plugin-svg-spritemap
5
6# pnpm
7pnpm add -D @twir/vite-plugin-svg-spritemap

👨‍💻 Usage

By default, the plugin will generate a spritemap to support all methods described below (files populated with <view> for fragments and <use> for sprite).

1// vite.config.js / vite.config.ts
2import VitePluginSvgSpritemap from '@twir/vite-plugin-svg-spritemap'
3
4export default {
5  plugins: [VitePluginSvgSpritemap('./src/icons/*.svg')]
6}

You can access to the spritemap via the route /__spritemap. All files process by ViteJS will transform the path of the file on build. By default, you will need to use the prefix sprite-.

SVG

1<svg>
2  <use xlink:href="/__spritemap#sprite-spiriit"></use>
3</svg>

Img

You need to add the suffix -view to access to the fragment.

1<img src="/__spritemap#sprite-spiriit-view" />

CSS

You can also use the spritemap SVGs in your CSS. The plugin supports CSS (basic classes) and also SCSS, Stylus and Less (mixins and map with SVG Data URI and sizes).

First you need to adjust the plugin options to set the output styles. For full styles options, check the Options.

1// vite.config.js / vite.config.ts
2import VitePluginSvgSpritemap from '@twir/vite-plugin-svg-spritemap'
3
4export default {
5  plugins: [
6    VitePluginSvgSpritemap('./src/icons/*.svg', {
7      styles: 'src/scss/spritemap.scss'
8    })
9  ]
10}

1// main.scss
2@import './spritemap.scss';

After that, you need to import the file in your current styles. Don't forget to load the CSS via ViteJS.

If you use a CSS preprocessing language, you can use the mixin sprite and access to a map with all sprites infos. If not, you will only access to classes.

You can see the usage in the demo folder :

• CSS
• SCSS
• Less
• Stylus

Use Vue components

vite-plugin-svg-spritemap allows you to load icons and create <use> as <svg> and <view> as <img> tags like Vue components.

To do that, import the icons loaded by vite-svg-spritemap and add the ?use or ?view query. The plugin will transform the component.

1<script setup lang="ts">
2import SpiriitView from './icons/spiriit.svg?view'
3import SpiriitUse from './icons/spiriit.svg?use'
4import ViteView from './icons/vite.svg?view'
5import ViteUse from './icons/vite.svg?use'
6</script>
7
8<template>
9  <SpiriitUse>
10    <!-- You can use the slot to pass a title before the use tag generation -->
11    <title>My superb logo</title>
12  </SpiriitUse>
13  <ViteUse />
14
15  <SpiriitView />
16  <ViteView />
17</template>

will generate

1<svg>
2  <title>My superb logo</title>
3  <use xlink:href="/__spritemap#sprite-spiriit"></use>
4</svg>
5<svg>
6  <use xlink:href="/__spritemap#sprite-vite"></use>
7</svg>
8<img src="/__spritemap#sprite-spiriit-view" width="118" height="38">
9<img src="/__spritemap#sprite-vite-view" width="31" height="32">

You can see the usage in the corresponding demo folder.

Typescript

For typescript, you need to load the type definitions inside vite-env.d.ts to fix errors with ?use/?view query.

1/// <reference types="vite/client" />
2/// <reference types="@twir/vite-plugin-svg-spritemap/client" />

Usage with Nuxt 3

[!NOTE] This plugin only works with Nuxt 3 and Vite as a bundler.

You just need to install the plugin and set it in the right place for Nuxt 3.

1// nuxt.config.ts
2import VitePluginSvgSpritemap from '@twir/vite-plugin-svg-spritemap'
3
4export default defineNuxtConfig({
5  vite: {
6    plugins: [
7      VitePluginSvgSpritemap('./assets/icons/*.svg'),
8    ]
9  }
10})

You can see the usage in the corresponding demo folder.

Typescript

For usage with TypeScript, you will need to add in a .d.ts file the reference type /// <reference types="@twir/vite-plugin-svg-spritemap/dist/client" /> (see issue #38) to use ?use/?view query.

1/// <reference types="@twir/vite-plugin-svg-spritemap/dist/client" />

Use for backend integration

ViteJS allows to be use to serve assets. So, you can connect ViteJS with Wordpress, Drupal or any kind of backend.

[!IMPORTANT] To make vite-plugin-svg-spritemap works with this kind of environnment, you will need to handle the right url inside your backend if you are on dev or build.

For example, with <use> on dev, using direcly the id of the svg (with the injectSVGOnDev option).

1<svg>
2  <use xlink:href="#sprite-spiriit"></use>
3</svg>

And in prod, by putting the correct URL manually thanks to the manifest.json file information :

1<svg>
2  <use xlink:href="https://my-cool-website.com/dist/assets/spritemap.95b4c41a.svg#sprite-spiriit"></use>
3</svg>

To prevent CORS issue with SVG and <use>, you can use the injectSVGOnDev option. Don't forget to add the HMR script directly above you close body.

1<script type="module" src="http://localhost:5173/@vite-plugin-svg-spritemap/client"></script>

You can see an example of integration in the corresponding demo folder.

🛠 Options

The first argument is a glob path (using fast-glob) and the second is an object with the following options :

Options	Type	Default	Description
output	boolean or object or string	true	As a string, set the destination of the file (see output.filename). For more control, see output. Set to false to disable output.
styles	false or object or string	false	File destination like src/css/spritemap.css or styles object
prefix	string or false	sprite-	Define the prefix uses for sprite id in <symbol>/<use>/<view>. Set to false to disable the prefix
svgo	boolean or object	true	Take an SVGO Options object. If true, it will use the default SVGO preset, if false, it will disable SVGO optimization
injectSVGOnDev	boolean	false	Inject the SVG Spritemap inside the body on dev
idify	(name:string, svg:object) => string	name => options.prefix + name	Function allowing to customize the id of each symbol of the spritemap svg.

output

Options	Type	Default	Description
filename	string	[name].[hash][extname]	The destination of the file. You can use output filename like Rollup. Note: Doesn't support hash number.
name	string	spritemap.svg	The name of file, appear on the manifest key
use	boolean	true	Insert use element in the spritemap
view	boolean	true	Insert view element in the spritemap

styles

Options	Type	Description
filename	string	The destination of the stylesheet file like your source folder
lang	less/scss/styl/css or undefined

Example with full options :

1// vite.config.js / vite.config.ts
2import VitePluginSVGSpritemap from '@twir/vite-plugin-svg-spritemap'
3
4export default {
5  plugins: [
6    VitePluginSVGSpritemap('./src/icons/*.svg', {
7      prefix: 'icon-',
8      output: {
9        filename: '[name].[hash][extname]',
10        name: 'spritemap.svg',
11        view: false,
12        use: true,
13      },
14      svgo: {
15        plugins: [
16          {
17            name: 'removeStyleElement',
18          },
19        ],
20      },
21      injectSVGOnDev: true,
22      idefy: (name, svg) => `icon-${name}-cheese`,
23      styles: {
24        lang: 'scss',
25        filename: 'src/scss/spritemap.scss'
26      }
27    })
28  ]
29}

🏃 What's next

• Support multiple instance of the plugin
• CSS generation callback
• Add variable supports inspired by svg-spritemap-webpack-plugin

👨‍💼 Licence

MIT