Registry / devops / vite-plugin-icons-spritesheet

vite-plugin-icons-spritesheet

library3.0.1jsnpmunverified

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).

devops

npm install vite-plugin-icons-spritesheet

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-ICONS-

vite-plugin-icons-spritesheet

devopsjavascriptv3.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

iconsSpritesheet

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

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

Named export only; default import does not exist.

IconsSpritesheetOptions

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

✗ import { 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.

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> ); }

Debug

Known issues

breakingv3.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.

affects: >=2.0.0 <3.0.0

breakingv2.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.

affects: >=1.0.0 <2.0.0

deprecatedv1.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.

affects: >=1.0.0 <2.0.0

gotchaThe 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.

affects: >=1.0.0

gotchaUsing 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.

affects: >=2.0.0

Errors

Common errors & fixes

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

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.

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

Missing package installation or incorrect import path.

fix

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

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

Using default import instead of named import.

fix

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

Upgrade

Version history

3.0.1latest on npm

Audit

Dependencies

viterequiredPeer dependency; plugin requires Vite >=5.2.0

Agent activity

3 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/forge42dev/vite-plugin-icons-spritesheet ↗

packagehttps://www.npmjs.com/package/vite-plugin-icons-spritesheet ↗