Better SVGR / SVGO default configs

[slorber]

Motivation

If you are an SVGR / SVGO expert, please help us find better defaults.

In #10677 we are creating a new @docusaurus/plugin-svgr plugin that you can now configure through plugin/preset options.

This plugin moves this core feature to a dedicated plugin:

import DocusaurusSvg from './docusaurus.svg';

<DocusaurusSvg />;

https://docusaurus.io/docs/markdown-features/assets#inline-svgs

This offers you escape hatches for when the default SVGR / SVGO config does not fit your needs.

But we'd still like to improve the Docusaurus SVGR / SVGO default configs

These configs define how you import and use SVG files in your React code, and changing those can break or fix existing sites by altering what gets rendered and how SVG components are converted to React components.

This would be a breaking change in an upcoming major version of Docusaurus (v4 for example).

We'd like to find defaults that work well for most sites and reduce the need for users to customize those configs. Optimizations should rather be safe and avoid potential SVG ids/class/whatever conflicts.

Current configs

These are the historical configs we use in Docusaurus v3:

const DefaultSVGOConfig: SVGOConfig = {
  plugins: [
    {
      name: 'preset-default',
      params: {
        overrides: {
          removeTitle: false,
          removeViewBox: false,
        },
      },
    },
  ],
};

const DefaultSVGRConfig: SVGRConfig = {
  prettier: false,
  svgo: true,
  svgoConfig: DefaultSVGOConfig,
  titleProp: true,
};

Related links

• Multiple inline SVGs on a page can clash #8297
• Unable to import SVG generated by Lucidchart failing with "SyntaxError: unknown file: Namespace tags are not supported by default" #10636
• chore: tailor svgo config for inline svgs #10205
• chore: load or create svgo.config.js #10211
• feat(svgr): create new Docusaurus SVGR plugin #10677

[hrumhurum]

SVGO project is notable for having some unsafe optimizations turned on by default, so this indeed creates problems.

This is what I have to use most of the times when embedding freestanding SVGs:

module.exports = {
  plugins: [
    {
      name: "preset-default",
      params: {
        overrides: {
          // Workaround SVGO issues by turning off particular optimizations.
          inlineStyles: false,
          removeUnknownsAndDefaults: false,
          convertShapeToPath: false
        }
      }
    }
  ]
};

Just my 2 cents. I tried to communicate about some of those issues to the SVGO project but they stay open indefinitely.

[SethFalco]

Disclaimer: I'm one of the maintainers of SVGO, so ofc I'll be more likely to stand by the project, even if I will concede it can be buggy.

We'd like to find defaults that work well for most sites and reduce the need for users to customize those configs.

The following config is what we use for svgo.dev now with SVGO v3, and I'd consider safe to use most if not all sites, unless you can point out a flaw with it!

Note, this config is only safe assuming it's given to SVGR and used to process SVGs that will be inlined into an HTML document. This config would not be suitable to give to a PostCSS plugin, for example.

I will annotate it with the reason for each setting.

{
  plugins: [
    // our default set of plugins
    {
      name: "preset-default",
      params: {
        overrides: {
          // disable for accessibility, slated to be disabled by default in SVGO v4
          removeTitle: false,
          // disable because it's dumb, slated to be disabled by default in SVGO v4
          removeViewBox: false,
          mergePaths: {
            // this is disabled by default because this optimization can break SVGs
            // in some old editors, however it's perfectly safe for browsers!
            noSpaceAfterFlags: true 
          }
        },
      },
      // this avoids conflicting ids across SVGs in the same HTML document
      {
          name: 'prefixIds',
          params: {
            delim: '',
            prefix: (_, info) => path.parse(info.path).name
          }
      },
      // this is disabled by default because it can break SVGs in local image viewers
      // or in SVG editors, however this plugin is 100% safe for SVGs that are
      // inlined into HTML because browsers ignore XML namespaces in attributes
      // (i.e. xlink:href is treated as href) 
      {
          name: 'removeXlink',
          params: {
            includeLegacy: true
          }
      },
      // disabled by default because this can mess with the auto-detected MIME-type
      // of SVGs and break viewing in some local image viewers, however this plugin
      // is 100% safe for SVGs that are inlined into HTML as browsers ignore XML
      // namespaces (xmlns) so it does nothing
      'removeXMLNS'
    }
  ]
}

I hope that helps, and questions welcome!

SVGO project is notable for having some unsafe optimizations turned on by default, so this indeed creates problems.

Some of the unsafe optimizations will be disabled by default in SVGO v4.0, such as removeViewBox and removeTitle. We're also working actively to patch bugs that may affect how an SVG is rendered.

I won't fault Docusaurus for playing it safe if they'd like to disable some of the plugins, but SVGO is a lot safer now than it was even a year ago! And we'll be continuing to patch any bugs that affect rendering.

I think SVGO is doing quite well, and is becoming more stable over time. We're also doing a lot to improve our QA to avoid accidentally breaking SVGs in updates. (Our regression test suite is huge now, with most of the KDE Oxygen Icons being compared before and after optimization per PR.)

Meanwhile, I'm sorry that bug fixes have been slow historically. The maintainers and myself can get pretty busy, but I'll personally try to set more time aside to tackle reports. 👍🏽

---

PS: I will be aiming to get SVGO v4.0 released soon. When that's done, I will notify you, and hopefully Docusaurus could upgrade to that before the major release. 🤞🏽

[slorber]

Thanks @SethFalco , I'll study all that and probably take your suggestions for the upcoming major version of Docusaurus. Maybe SVGO v4 will also be released at that time.