Registry / web-framework / esbuild-svg-symbol-plugin

esbuild-svg-symbol-plugin

library1.0.1jsnpmunverified

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.

web-framework serialization

npm install esbuild-svg-symbol-plugin

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-SVG-SYMBOL

esbuild-svg-symbol-plugin

web-frameworkjavascriptv1.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

svgSymbolLoaderPlugin

✓ import svgSymbolLoaderPlugin from 'esbuild-svg-symbol-plugin'

✗ const svgSymbolLoaderPlugin = require('esbuild-svg-symbol-plugin')

Plugin is exported as default. CommonJS require breaks if package is ESM-only (check package.json).

config

✓ import svgSymbolLoaderPlugin from 'esbuild-svg-symbol-plugin'; const config = { esModule: true }

✗ const { svgSymbolLoaderPlugin } = require('esbuild-svg-symbol-plugin')

Only default export exists. Named import will result in undefined.

SpriteSymbol

✓ import SpriteSymbol from 'esbuild-svg-symbol-plugin/runtime/symbol'

Runtime symbol class for manual use. Not part of main plugin export.

Setup esbuild with svg symbol loader plugin, import SVG as symbol with id and viewBox.

import esbuild from 'esbuild'; import svgSymbolLoaderPlugin from 'esbuild-svg-symbol-plugin'; await esbuild.build({ entryPoints: ['src/index.js'], bundle: true, outfile: 'dist/bundle.js', plugins: [svgSymbolLoaderPlugin()], }).catch(e => (console.error(e), process.exit(1))); // src/index.js import twitterLogo from './logos/twitter.svg'; console.log(twitterLogo.id); // symbol id console.log(twitterLogo.viewBox); // viewBox value // In HTML: <svg><use href="#generated-symbol-id"></use></svg>

Debug

Known issues

gotchaPlugin does not extract sprite to separate file; all symbols are inlined into JS bundle.

fix

For external sprite extraction, use svg-sprite-loader with webpack instead.

affects: >=1.0.0

deprecatedOptions like `esModule` default to true and may cause issues with CJS projects.

fix

Set `esModule: false` in plugin config for CommonJS output modules.

affects: >=1.0.0

breakingThe plugin renames imported SVG symbols; do not rely on original file names for IDs.

fix

Access symbol ID via the returned object's `id` property, not via filename.

affects: >=1.0.0

gotchaDOMContentLoaded auto-injection may conflict with frameworks that manage DOM manually.

fix

Provide a custom `spriteModule` to control injection timing and target.

affects: >=1.0.0

gotchaDynamic import of SVGs may cause duplicate symbol registration if same file imported multiple times.

fix

Ensure dynamic imports are deduplicated or use static imports for reused icons.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'esbuild-svg-symbol-plugin'

Package not installed as devDependency

fix

Run `npm install esbuild-svg-symbol-plugin --save-dev` or `yarn add esbuild-svg-symbol-plugin --dev`.

TypeError: svgSymbolLoaderPlugin is not a function

Named import instead of default import

fix

Use `import svgSymbolLoaderPlugin from 'esbuild-svg-symbol-plugin'` (without curly braces).

Error: The module './logos/twitter.svg' could not be found

File path incorrect or SVG not recognized by plugin

fix

Verify SVG path relative to entry point and ensure plugin is listed in esbuild plugins array.

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

esbuildrequiredpeer dependency - plugin is designed for esbuild

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/KrakenTyio/esbuild-svg-symbol-plugin ↗

packagehttps://www.npmjs.com/package/esbuild-svg-symbol-plugin ↗