{"id":22730,"library":"vite-plugin-magical-svg","title":"Vite Plugin Magical SVG","description":"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.","status":"active","version":"1.9.0","language":"javascript","source_language":"en","source_url":"https://github.com/cyyynthia/vite-plugin-magical-svg","tags":["javascript","vite-plugin","spritesheet","sprite","svgr","svg","typescript"],"install":[{"cmd":"npm install vite-plugin-magical-svg","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-magical-svg","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-magical-svg","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency: requires Vite >= 3.0.0","package":"vite","optional":false}],"imports":[{"note":"Default export is the plugin function. Dual CJS/ESM build since v1.7.1; ESM import is preferred.","wrong":"const magicalSvg = require('vite-plugin-magical-svg')","symbol":"magicalSvg","correct":"import magicalSvg from 'vite-plugin-magical-svg'"},{"note":"Named export is not available; must use default import.","wrong":"import { magicalSvg } from 'vite-plugin-magical-svg'","symbol":"magicalSvg","correct":"import magicalSvg from 'vite-plugin-magical-svg'"},{"note":"To import an SVG as a component, use the ?component query suffix for targets like React, Preact, Vue, etc.","wrong":"import SvgComponent from './icon.svg'","symbol":"SvgComponent","correct":"import SvgComponent from './icon.svg?component'"},{"note":"Use ?url to get the SVG file URL directly, useful for <img> src or fetch.","wrong":"import svgUrl from './icon.svg'","symbol":"svgUrl","correct":"import svgUrl from './icon.svg?url'"}],"quickstart":{"code":"// vite.config.js\nimport { defineConfig } from 'vite'\nimport magicalSvg from 'vite-plugin-magical-svg'\nimport preact from '@preact/preset-vite'\n\nexport default defineConfig({\n  plugins: [\n    magicalSvg({ target: 'preact', svgo: true }),\n    preact()\n  ]\n})\n\n// App.jsx\nimport MyIcon from './icons/alert.svg?component'\n\nexport default function App() {\n  return (\n    <div>\n      <h1>Hello, Magical SVG!</h1>\n      <MyIcon width={24} height={24} fill=\"currentColor\" />\n    </div>\n  )\n}","lang":"javascript","description":"Shows setup with Preact target and usage of an SVG as a component with custom props."},"warnings":[{"fix":"Upgrade to v1.7.3 or later; v1.7.2 is broken.","message":"v1.7.2: Runtime scripts were not importable due to incorrect export configuration.","severity":"breaking","affected_versions":"1.7.2"},{"fix":"Use default import: import magicalSvg from 'vite-plugin-magical-svg'. No path changes required for most users.","message":"v1.7.1: Changed from faux ESM to real dual-build (ESM + CJS). Import paths may need updating.","severity":"breaking","affected_versions":">=1.7.1"},{"fix":"Always use explicit query suffix (e.g., ./icon.svg?component) to import SVGs.","message":"Importing SVGs without a query suffix (e.g., ?component, ?url) may be deprecated in future versions.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Ensure SVG imports are static: import Icon from './icon.svg?component'","message":"Tree-shaking only works when SVGs are imported statically (not dynamically) and with the ?component suffix.","severity":"gotcha","affected_versions":">=1.5.0"},{"fix":"No action needed; sprites are only generated in production builds.","message":"Sprite generation is disabled during development for HMR performance; SVGs are embedded inline instead.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run 'npm install vite-plugin-magical-svg' (or yarn/pnpm). For ESM, ensure you are using import syntax.","cause":"Package not installed or module resolution issue.","error":"Error: Cannot find module 'vite-plugin-magical-svg'"},{"fix":"Change to: import magicalSvg from 'vite-plugin-magical-svg'","cause":"Named import used instead of default import.","error":"TypeError: magicalSvg is not a function"},{"fix":"Use: import icon from './icon.svg?component'","cause":"SVG imported without query suffix; the plugin's virtual module expects a ?component or ?url suffix.","error":"Uncaught SyntaxError: The requested module './icon.svg' does not provide an export named 'default'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}