Registry / web-framework / vite-plugin-magical-svg

vite-plugin-magical-svg

library1.9.0jsnpmunverified

An all-in-one Vite plugin (v1.9.0) for SVG imports that bundles SVGs into spritesheets, supports tree-shaking, and processes referenced assets. Key differentiators vs alternatives like SVGR or vite-plugin-svg-icons: resolves references (e.g., <image href>) inside SVGs, allows selective exclusion per SVG via query parameters, supports multiple output targets (React, Preact, Vue, Solid, Svelte, Ember, Lit, vanilla DOM), and provides experimental features like recoloring control and width/height normalization. Shipped with TypeScript types, requires Vite >= 3.0.0, and follows a fast release cadence with frequent dependency upgrades.

web-framework

npm install vite-plugin-magical-svg

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-MAGICA

vite-plugin-magical-svg

web-frameworkjavascriptv1.9.0

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.

magicalSvg

✓ import magicalSvg from 'vite-plugin-magical-svg'

✗ const magicalSvg = require('vite-plugin-magical-svg')

Default export is the plugin function. Dual CJS/ESM build since v1.7.1; ESM import is preferred.

magicalSvg

✓ import magicalSvg from 'vite-plugin-magical-svg'

✗ import { magicalSvg } from 'vite-plugin-magical-svg'

Named export is not available; must use default import.

SvgComponent

✓ import SvgComponent from './icon.svg?component'

✗ import SvgComponent from './icon.svg'

To import an SVG as a component, use the ?component query suffix for targets like React, Preact, Vue, etc.

svgUrl

✓ import svgUrl from './icon.svg?url'

✗ import svgUrl from './icon.svg'

Use ?url to get the SVG file URL directly, useful for <img> src or fetch.

Shows setup with Preact target and usage of an SVG as a component with custom props.

// vite.config.js import { defineConfig } from 'vite' import magicalSvg from 'vite-plugin-magical-svg' import preact from '@preact/preset-vite' export default defineConfig({ plugins: [ magicalSvg({ target: 'preact', svgo: true }), preact() ] }) // App.jsx import MyIcon from './icons/alert.svg?component' export default function App() { return ( <div> <h1>Hello, Magical SVG!</h1> <MyIcon width={24} height={24} fill="currentColor" /> </div> ) }

Debug

Known issues

breakingv1.7.2: Runtime scripts were not importable due to incorrect export configuration.

fix

Upgrade to v1.7.3 or later; v1.7.2 is broken.

affects: 1.7.2

breakingv1.7.1: Changed from faux ESM to real dual-build (ESM + CJS). Import paths may need updating.

fix

Use default import: import magicalSvg from 'vite-plugin-magical-svg'. No path changes required for most users.

affects: >=1.7.1

deprecatedImporting SVGs without a query suffix (e.g., ?component, ?url) may be deprecated in future versions.

fix

Always use explicit query suffix (e.g., ./icon.svg?component) to import SVGs.

affects: >=1.0.0

gotchaTree-shaking only works when SVGs are imported statically (not dynamically) and with the ?component suffix.

fix

Ensure SVG imports are static: import Icon from './icon.svg?component'

affects: >=1.5.0

gotchaSprite generation is disabled during development for HMR performance; SVGs are embedded inline instead.

fix

No action needed; sprites are only generated in production builds.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'vite-plugin-magical-svg'

Package not installed or module resolution issue.

fix

Run 'npm install vite-plugin-magical-svg' (or yarn/pnpm). For ESM, ensure you are using import syntax.

TypeError: magicalSvg is not a function

Named import used instead of default import.

fix

Change to: import magicalSvg from 'vite-plugin-magical-svg'

Uncaught SyntaxError: The requested module './icon.svg' does not provide an export named 'default'

SVG imported without query suffix; the plugin's virtual module expects a ?component or ?url suffix.

fix

Use: import icon from './icon.svg?component'

Upgrade

Version history

1.9.0latest on npm

Audit

Dependencies

viterequiredpeer dependency: requires Vite >= 3.0.0

Agent activity

10 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/cyyynthia/vite-plugin-magical-svg ↗

packagehttps://www.npmjs.com/package/vite-plugin-magical-svg ↗