esbuild-svg-symbol-plugin

1.0.1 verified Fri May 01 auth: no javascript

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.

Common errors

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

cause Package not installed as devDependency

fix

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

error TypeError: svgSymbolLoaderPlugin is not a function ↓

cause Named import instead of default import

fix

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

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

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

Warnings

gotcha Plugin 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.

deprecated Options like `esModule` default to true and may cause issues with CJS projects. ↓

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

breaking The 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.

gotcha DOMContentLoaded auto-injection may conflict with frameworks that manage DOM manually. ↓

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

gotcha Dynamic 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.

Install

npm install esbuild-svg-symbol-plugin

yarn add esbuild-svg-symbol-plugin

pnpm add esbuild-svg-symbol-plugin

Imports

svgSymbolLoaderPlugin

wrong

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

correct

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

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

config

wrong

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

correct

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

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.

Quickstart

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>