esbuild-plugin-svg

0.1.0 verified Mon Apr 27 auth: no javascript

An esbuild plugin for importing SVG files as strings or custom elements, with optional SVGO minification. Version 0.1.0 is the initial release. It wraps SVGO (included) to optimize SVGs on build. Compared to alternatives like esbuild-svg-loader, it offers both string and custom element modes out of the box.

Common errors

error Error: Can't resolve 'esbuild-plugin-svg' ↓

cause Package not installed or import path incorrect.

fix

Install the package: npm install esbuild-plugin-svg

error TypeError: svg is not a function ↓

cause Using named import instead of default import.

fix

Use: import svg from 'esbuild-plugin-svg'

error Error: Invalid or unexpected token ↓

cause ESM syntax in CommonJS context without 'type': 'module'.

fix

Add "type": "module" to package.json or use .mjs extension.

Warnings

gotcha Plugin is ESM-only; cannot be used with CommonJS require(). ↓

fix Use import or set type: 'module' in your package.json.

gotcha The 'minifyOptions' property expects SVGO plugin options, not general options. ↓

fix Pass an object with a 'plugins' array as per SVGO API.

gotcha In customElement mode, custom element names are derived from the filename with a namespace prefix; conflicts may arise. ↓

fix Ensure filenames are unique or override namespace.

Install

npm install esbuild-plugin-svg

yarn add esbuild-plugin-svg

pnpm add esbuild-plugin-svg

Imports

default

wrong

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

correct

import svg from 'esbuild-plugin-svg'

The plugin is ESM-only; CommonJS require will fail.

svg

wrong

import { svg } from 'esbuild-plugin-svg'

correct

import svg from 'esbuild-plugin-svg'

The module exports a default function, not a named export.

svg (with options)

wrong

svg({ customElement: 'true', minify: 'true' })

correct

svg({ customElement: true, minify: true })

Options are boolean, not strings.

Quickstart

Shows basic usage of esbuild-plugin-svg with default options (string mode, no minification).

import esbuild from 'esbuild';
import svg from 'esbuild-plugin-svg';

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [svg()]
}).catch(() => process.exit(1));