esbuild-svg

1.0.3 verified Fri May 01 auth: no javascript

esbuild-svg 1.0.3 is an esbuild plugin that transforms SVG files into JSX React components using SVGR under the hood. It supports both default and named exports, configurable SVGO optimization, and provides a publicPath feature via a special import suffix. Currently stable, it releases occasionally. Compared to alternatives like @svgr/webpack or vite-plugin-svgr, it is tailored specifically for esbuild and integrates tightly with its publicPath configuration. It ships TypeScript definitions and requires React (peer dependency) for JSX rendering.

Common errors

error Cannot find module 'esbuild-svg' ↓

cause Package not installed or missing from dependencies.

fix

Run npm install --save-dev esbuild-svg

error TypeError: svgPlugin is not a function ↓

cause Incorrect import style (e.g., commonjs require on ESM-only build).

fix

Use import svgPlugin from 'esbuild-svg' or const { default: svgPlugin } = require('esbuild-svg')

error Uncaught ReferenceError: React is not defined ↓

cause Missing React peer dependency.

fix

Install react: npm install react

error Module parse failed: Unexpected token (1:0) ↓

cause esbuild not configured to handle JSX output from SVG transformation.

fix

Ensure esbuild's loader is set for .jsx/.tsx files, or use esbuild's JSX automatic runtime.

Warnings

gotcha The plugin requires React as a peer dependency for JSX output. If not installed, you may get runtime errors when components are used. ↓

fix Install react: npm install react

breaking Version 1.0.0 changed the default SVGR export from default to named. Existing code importing SVGs without exportType config will break. ↓

fix Set svgPlugin({ exportType: 'default' }) to restore old behavior, or update imports to use { ReactComponent } named import.

gotcha The '?' suffix for publicPath only works with esbuild's publicPath configuration. Without it, the URL may be incorrect or lead to 404 errors. ↓

fix Ensure esbuild build options include publicPath: '/assets/' (or similar).

Install

npm install esbuild-svg

yarn add esbuild-svg

pnpm add esbuild-svg

Imports

svgPlugin
wrong
```
const svgPlugin = require('esbuild-svg')
```
correct
```
import svgPlugin from 'esbuild-svg'
```
Package ships both ESM and CJS. Default import works in both, but require() may have issues if the package is used in ESM context.
ReactComponent
wrong
```
import ReactComponent from '../pic/dummy.svg'
```
correct
```
import { ReactComponent } from '../pic/dummy.svg'
```
Named export 'ReactComponent' is used when SVGR config has exportType: 'named' (default). Wrong default import will result in undefined.
publicPath
wrong
```
import path from '../pic/dummy.svg'
```
correct
```
import path from '../pic/dummy.svg?'
```
Appending '?' to the import path returns the SVG's public URL string instead of a component. Omitting '?' returns the component.

Quickstart

Configures esbuild with the SVG plugin to transform SVG imports into React components using default SVGR settings.

import esbuild from 'esbuild';
import svgPlugin from 'esbuild-svg';

await esbuild.build({
  entryPoints: ['src/index.jsx'],
  outdir: 'dist',
  bundle: true,
  plugins: [svgPlugin()],
});