{"id":25457,"library":"esbuild-svg-symbol-plugin","title":"esbuild-svg-symbol-plugin","description":"Esbuild plugin (v1.0.1) for loading SVG icons as inline SVG symbols during build, enabling efficient client-side use via <use> tags. Inspired by svg-sprite-loader, this plugin handles runtime rendering in browsers and Node.js without sprite extraction. It automatically injects a sprite containing all referenced SVG symbols into the DOM on DOMContentLoaded. Supports ESM and CJS output, customizable sprite and symbol modules, and dynamic imports. Minimal configuration needed, with autodetection of esModule format based on webpack version. Git-based releases, low maintenance cadence.","status":"active","version":"1.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/KrakenTyio/esbuild-svg-symbol-plugin","tags":["javascript","svg","symbol","svg symbol","svg stack","esbuild","esbuild plugin"],"install":[{"cmd":"npm install esbuild-svg-symbol-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-svg-symbol-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-svg-symbol-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency - plugin is designed for esbuild","package":"esbuild","optional":false}],"imports":[{"note":"Plugin is exported as default. CommonJS require breaks if package is ESM-only (check package.json).","wrong":"const svgSymbolLoaderPlugin = require('esbuild-svg-symbol-plugin')","symbol":"svgSymbolLoaderPlugin","correct":"import svgSymbolLoaderPlugin from 'esbuild-svg-symbol-plugin'"},{"note":"Only default export exists. Named import will result in undefined.","wrong":"const { svgSymbolLoaderPlugin } = require('esbuild-svg-symbol-plugin')","symbol":"config","correct":"import svgSymbolLoaderPlugin from 'esbuild-svg-symbol-plugin'; const config = { esModule: true }"},{"note":"Runtime symbol class for manual use. Not part of main plugin export.","wrong":"","symbol":"SpriteSymbol","correct":"import SpriteSymbol from 'esbuild-svg-symbol-plugin/runtime/symbol'"}],"quickstart":{"code":"import esbuild from 'esbuild';\nimport svgSymbolLoaderPlugin from 'esbuild-svg-symbol-plugin';\n\nawait esbuild.build({\n  entryPoints: ['src/index.js'],\n  bundle: true,\n  outfile: 'dist/bundle.js',\n  plugins: [svgSymbolLoaderPlugin()],\n}).catch(e => (console.error(e), process.exit(1)));\n\n// src/index.js\nimport twitterLogo from './logos/twitter.svg';\nconsole.log(twitterLogo.id); // symbol id\nconsole.log(twitterLogo.viewBox); // viewBox value\n\n// In HTML: <svg><use href=\"#generated-symbol-id\"></use></svg>","lang":"typescript","description":"Setup esbuild with svg symbol loader plugin, import SVG as symbol with id and viewBox."},"warnings":[{"fix":"For external sprite extraction, use svg-sprite-loader with webpack instead.","message":"Plugin does not extract sprite to separate file; all symbols are inlined into JS bundle.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set `esModule: false` in plugin config for CommonJS output modules.","message":"Options like `esModule` default to true and may cause issues with CJS projects.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Access symbol ID via the returned object's `id` property, not via filename.","message":"The plugin renames imported SVG symbols; do not rely on original file names for IDs.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Provide a custom `spriteModule` to control injection timing and target.","message":"DOMContentLoaded auto-injection may conflict with frameworks that manage DOM manually.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure dynamic imports are deduplicated or use static imports for reused icons.","message":"Dynamic import of SVGs may cause duplicate symbol registration if same file imported multiple times.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run `npm install esbuild-svg-symbol-plugin --save-dev` or `yarn add esbuild-svg-symbol-plugin --dev`.","cause":"Package not installed as devDependency","error":"Error: Cannot find module 'esbuild-svg-symbol-plugin'"},{"fix":"Use `import svgSymbolLoaderPlugin from 'esbuild-svg-symbol-plugin'` (without curly braces).","cause":"Named import instead of default import","error":"TypeError: svgSymbolLoaderPlugin is not a function"},{"fix":"Verify SVG path relative to entry point and ensure plugin is listed in esbuild plugins array.","cause":"File path incorrect or SVG not recognized by plugin","error":"Error: The module './logos/twitter.svg' could not be found"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}