Vite Plugin Icons Spritesheet

3.0.1 verified Mon Apr 27 auth: no javascript

Vite plugin (v3.0.1) that generates an SVG spritesheet and optional TypeScript type definitions from a folder of SVG icons. Watches the input directory and rebuilds on changes. Supports multiple spritesheet configurations, custom icon naming via transformer function, and integration with Prettier or Biome for formatting. Respects Vite's assetInlineLimit configuration. Requires Vite >=5.2.0 as a peer dependency. Differentiated by its focus on spritesheet generation with HMR support and framework-agnostic design (React, Vue, Angular, Remix).

Common errors

error Error: The plugin 'vite-plugin-icons-spritesheet' requires Vite >=5.2.0 ↓

cause Installed plugin version 3.x with an older Vite version (<5.2.0).

fix

Upgrade Vite to >=5.2.0: npm install vite@latest or adjust plugin to v2.x if Vite downgrade not possible.

error Cannot find module 'vite-plugin-icons-spritesheet' or its corresponding type declarations. ↓

cause Missing package installation or incorrect import path.

fix

Install the package: npm install -D vite-plugin-icons-spritesheet. Verify it's in devDependencies.

error Module '"vite-plugin-icons-spritesheet"' has no exported member 'iconsSpritesheet'. ↓

cause Using default import instead of named import.

fix

Change import iconsSpritesheet from ... to import { iconsSpritesheet } from ....

Warnings

breaking v3.0.0 removed the `formatterConfigPath` option; formatters now use project config automatically. ↓

fix Remove `formatterConfigPath` from your config. Ensure Prettier or Biome config file is present in the project root.

breaking v2.0.0 changed the TypeScript type output to use the generated array instead of duplicating symbols; may break type imports expecting an enum or union with specific style. ↓

fix Update type imports: the type output is now a string union derived from the icon file names. Adjust any icon name literals if they differ.

deprecated v1.x used `inputDir` as the only required option; v2+ supports multiple configs via array. Single config still works, but array is preferred for multiple spritesheets. ↓

fix If you have multiple icon folders, wrap your single config in an array or use multiple separate config objects.

gotcha The plugin does NOT remove previous sprite.svg or types when input icons are deleted; stale references may remain. ↓

fix Manually delete `outputDir/sprite.svg` and `typesOutputFile` if you remove icons. Or implement a custom cleanup script.

gotcha Using CommonJS `require()` to import the plugin in a Vite config that uses ESM may fail. Ensure your `vite.config.js` uses ESM syntax or a .mjs extension. ↓

fix Use `import { iconsSpritesheet } from 'vite-plugin-icons-spritesheet'` and set `"type": "module"` in package.json or use .mjs file.

Install

npm install vite-plugin-icons-spritesheet

yarn add vite-plugin-icons-spritesheet

pnpm add vite-plugin-icons-spritesheet

Imports

iconsSpritesheet

wrong

import iconsSpritesheet from 'vite-plugin-icons-spritesheet'

correct

import { iconsSpritesheet } from 'vite-plugin-icons-spritesheet'

Named export only; default import does not exist.

IconsSpritesheetOptions

wrong

import { IconsSpritesheetOptions } from 'vite-plugin-icons-spritesheet'

correct

import type { IconsSpritesheetOptions } from 'vite-plugin-icons-spritesheet'

Type-only import for TypeScript users; never use value import for types.

require (CommonJS)

const { iconsSpritesheet } = require('vite-plugin-icons-spritesheet')

CommonJS require is supported via named destructuring.

Quickstart

Plugin setup with TypeScript types and React component example using the generated spritesheet.

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { iconsSpritesheet } from 'vite-plugin-icons-spritesheet';

export default defineConfig({
  plugins: [
    react(),
    iconsSpritesheet({
      withTypes: true,
      inputDir: 'icons',
      outputDir: 'public/icons',
      fileName: 'sprite.svg',
      formatter: 'prettier',
    }),
  ],
});

// Place SVG files in the 'icons' directory, then reference them:
// In your React component:
import spriteHref from '/icons/sprite.svg';
import type { IconName } from '/icons/types';

export function Icon({ name, ...props }: React.SVGProps<SVGSVGElement> & { name: IconName }) {
  return (
    <svg {...props}>
      <use href={`${spriteHref}#${name}`} />
    </svg>
  );
}