eslint-plugin-svgo

An ESLint plugin that brings the power of SVGO to your SVG optimization workflow.

Optimize SVG files with SVGO via ESLint rules, enabling seamless integration into your development and CI/CD pipelines.

✨ Features

• 🚀 Full integration with SVGO v4+
• 📋 Lint SVG files with ESLint
• ⚙️ Highly configurable SVGO plugins
• 🔧 Support for external SVGO config files
• 📦 Works with ESLint's flat config format
• 🎯 TypeScript support

Compatibility

Package	Version
SVGO	v4.0.0+
ESLint	v9.5.0+
Node.js	v20.0.0+

📦 Installation

Choose your package manager:

npm i eslint-plugin-svgo -D

yarn add eslint-plugin-svgo -D

pnpm add eslint-plugin-svgo -D

🚀 Quick Start

The quickest way to get started - use the recommended configuration:

// eslint.config.js
import { defineConfig } from 'eslint/config'
import pluginSVGO from 'eslint-plugin-svgo'

export default defineConfig([
  // Your other configs...
  pluginSVGO.configs.recommended,
])

This will automatically:

• Target all **/*.svg files
• Enable the svgo/svgo rule with sensible defaults
• Use the preset-default SVGO plugin configuration

🎯 Advanced Usage

For more control over the SVGO optimization process, configure the plugin manually:

// eslint.config.js
import { defineConfig } from 'eslint/config'
import { parserPlain, plugin as pluginSVGO } from 'eslint-plugin-svgo'

export default defineConfig([
  {
    name: 'svgo',
    files: ['**/*.svg'],
    ignores: ['icons/foo.svg', 'images/**/*.svg'],
    plugins: {
      svgo: pluginSVGO,
    },
    languageOptions: {
      parser: parserPlain,
    },
    rules: {
      'svgo/svgo': [
        'error',
        {
          floatPrecision: 2,
          js2svg: {
            pretty: true,
          },
          plugins: [
            'preset-default',
            {
              name: 'cleanupIds',
              params: {
                minify: false,
              },
            },
          ],
        },
      ],
    },
  },
])

Plugin Configuration Options

You can configure SVGO plugins in two ways:

1. By plugin name (using defaults):

import { defineConfig } from 'eslint/config'
import pluginSVGO from 'eslint-plugin-svgo'

export default defineConfig([
  // Your other configs...
  {
    ...pluginSVGO.configs.recommended,
    rules: {
      'svgo/svgo': [
        'error',
        {
          plugins: ['cleanupIds', 'convertColors'],
        },
      ],
    },
  },
])

2. With custom parameters:

import { defineConfig } from 'eslint/config'
import pluginSVGO from 'eslint-plugin-svgo'

export default defineConfig([
  // Your other configs...
  {
    ...pluginSVGO.configs.recommended,
    rules: {
      'svgo/svgo': [
        'error',
        {
          plugins: [
            {
              name: 'cleanupIds',
              params: {
                minify: false,
              },
            },
          ],
        },
      ],
    },
  },
])

3. Override preset defaults:

import { defineConfig } from 'eslint/config'
import pluginSVGO from 'eslint-plugin-svgo'

export default defineConfig([
  // Your other configs...
  {
    ...pluginSVGO.configs.recommended,
    rules: {
      'svgo/svgo': [
        'error',
        {
          plugins: [
            {
              name: 'preset-default',
              params: {
                overrides: {
                  cleanupAttrs: false,
                  cleanupIds: {
                    minify: false,
                  },
                },
              },
            },
          ],
        },
      ],
    },
  },
])

🔌 Integration Guides

VSCode

Enable ESLint validation for SVG files by adding to your .vscode/settings.json:

{
  "eslint.validate": ["xml", "svg"]
}

Prettier

Add SVG files to your .prettierignore to prevent conflicts with ESLint:

**/*.svg

Or configure in package.json:

{
  "prettier": {
    "ignorePatterns": ["**/*.svg"]
  }
}

📚 Rule Reference

svgo/svgo

Optimize SVG files using SVGO.

Options

svgoConfig

• Type: boolean | string
• Default: undefined
• Example: true or './svgo.config.js'

Use an external SVGO config file. This is useful when you need to use features that aren't JSON-schema compatible (like function-based configuration).

• true — Auto-load svgo.config.mjs or svgo.config.js from your project root
• 'path/to/config' — Use a specific config file path

Behavior details:

• When svgoConfig is true, the rule auto-searches for a SVGO config file from the SVG file directory upward.
• If no external config is found with svgoConfig: true, the rule falls back to in-rule options (plugins, floatPrecision, etc.).
• When svgoConfig is a string path, that path must exist and be loadable, otherwise the rule reports an optimization error.
• When an external config is loaded successfully, other rule options (except path) are ignored.

reportMode

• Type: 'diff' | 'summary'
• Default: 'diff'

Choose how diagnostics are reported when SVG can be optimized:

• 'diff' — Report each text diff as a separate ESLint message (detailed)
• 'summary' — Report a single ESLint message with a full-file autofix (quiet CI output)

Set ESLINT_PLUGIN_SVGO_DEBUG=1 (or DEBUG=eslint-plugin-svgo) to include error stacks in diagnostic messages.

path

• Type: string
• Default: context.filename

Override the file path. Some plugins (like prefixIds) use this for context.

multipass

• Type: boolean
• Default: false

Enable multiple optimization passes to ensure all optimizations are fully applied.

floatPrecision

• Type: number
• Default: 3

Set precision for floating-point numbers in the output (e.g., 2 converts 1.234 to 1.23). This is passed to plugins that support it.

datauri

• Type: 'base64' | 'enc' | 'unenc'
• Default: undefined

Output format for Data URIs:

• 'base64' — Base64 encoded
• 'enc' — URL-encoded
• 'unenc' — Unencoded

js2svg

• Type: object
• Default: undefined

Options for rendering the optimized SVG from the AST. See SVGO's js2svg documentation for all available options.

Common options:

import { defineConfig } from 'eslint/config'
import pluginSVGO from 'eslint-plugin-svgo'

export default defineConfig([
  // Your other configs...
  {
    ...pluginSVGO.configs.recommended,
    rules: {
      'svgo/svgo': [
        'error',
        {
          js2svg: {
            pretty: true, // Add newlines and indentation
            indent: 2, // Indentation size
            eol: 'lf', // Line ending style
            final: true, // Add final newline
          },
        },
      ],
    },
  },
])

Unsupported options: regEntities, regValEntities, encodeEntity (require functions)

plugins

• Type: array
• Default: ['preset-default']

List of SVGO plugins to apply. See SVGO's plugin documentation for available plugins and their parameters.

Example configuration:

import { defineConfig } from 'eslint/config'
import pluginSVGO from 'eslint-plugin-svgo'

export default defineConfig([
  // Your other configs...
  {
    ...pluginSVGO.configs.recommended,
    rules: {
      'svgo/svgo': [
        'error',
        {
          plugins: [
            'preset-default',
            'removeDoctype',
            {
              name: 'cleanupIds',
              params: {
                minify: false,
                prefix: 'icon-',
              },
            },
          ],
        },
      ],
    },
  },
])

⚠️ JSON Schema Limitations

ESLint rule options must be JSON schema compatible, which means functions and regular expressions cannot be used directly in rule options. However, you can work around this using external config files.

Unsupported Features in Rule Options

js2svg:

• regEntities — function
• regValEntities — function
• encodeEntity — function

plugins:

• prefixIds.prefix — function (use boolean or string instead)
• addClassesToSVGElement.className — function (use string instead)
• convertColors.currentColor — regexp (use boolean or string instead)
• removeComments.preservePatterns — regexp (use boolean or string instead)

Solution: Use External Config

For advanced configurations requiring functions or regexes, create an external config file:

// svgo.config.mjs
export default {
  plugins: [
    'preset-default',
    {
      name: 'prefixIds',
      params: {
        prefix: node => `svg-${node.attributes.id}`,
      },
    },
  ],
}

Then reference it in your ESLint config:

import { defineConfig } from 'eslint/config'
import pluginSVGO from 'eslint-plugin-svgo'

export default defineConfig([
  // Your other configs...
  {
    ...pluginSVGO.configs.recommended,
    rules: {
      'svgo/svgo': ['error', { svgoConfig: './svgo.config.mjs' }],
    },
  },
])

Tip: External config files are the most flexible way to configure SVGO with all its advanced features.

💡 Common Examples

Basic SVG Optimization

import { defineConfig } from 'eslint/config'
import pluginSVGO from 'eslint-plugin-svgo'

export default defineConfig([
  // Your other configs...
  {
    ...pluginSVGO.configs.recommended,
    rules: {
      'svgo/svgo': 'error',
    },
  },
])

With Custom Float Precision

import { defineConfig } from 'eslint/config'
import pluginSVGO from 'eslint-plugin-svgo'

export default defineConfig([
  // Your other configs...
  {
    ...pluginSVGO.configs.recommended,
    rules: {
      'svgo/svgo': [
        'error',
        {
          floatPrecision: 2,
        },
      ],
    },
  },
])

Pretty-Printed SVG Output

import { defineConfig } from 'eslint/config'
import pluginSVGO from 'eslint-plugin-svgo'

export default defineConfig([
  // Your other configs...
  {
    ...pluginSVGO.configs.recommended,
    rules: {
      'svgo/svgo': [
        'error',
        {
          js2svg: {
            pretty: true,
            indent: 2,
          },
        },
      ],
    },
  },
])

Disable Specific Plugins

import { defineConfig } from 'eslint/config'
import pluginSVGO from 'eslint-plugin-svgo'

export default defineConfig([
  // Your other configs...
  {
    ...pluginSVGO.configs.recommended,
    rules: {
      'svgo/svgo': [
        'error',
        {
          plugins: [
            {
              name: 'preset-default',
              params: {
                overrides: {
                  removeDoctype: false,
                  removeComments: false,
                },
              },
            },
          ],
        },
      ],
    },
  },
])

Using External Config

import { defineConfig } from 'eslint/config'
import pluginSVGO from 'eslint-plugin-svgo'

export default defineConfig([
  // Your other configs...
  {
    ...pluginSVGO.configs.recommended,
    rules: {
      'svgo/svgo': ['error', { svgoConfig: true }],
    },
  },
])

With svgo.config.mjs:

export default {
  multipass: true,
  floatPrecision: 2,
  plugins: [
    'preset-default',
    'removeDoctype',
    {
      name: 'cleanupIds',
      params: { minify: false },
    },
  ],
}

💖 Acknowledgments

• antfu/eslint-plugin-format — Inspiration for plugin structure
• SVGO — The powerful SVG optimization library
• ESLint — Pluggable linting utility

📄 License

MIT License © 2024-PRESENT ntnyq