Error: Invalid configuration: plugins must be an array – cleanupIDs plugin behavior across files

Cross-File Reference Behavior

The cleanupIDs plugin in SVGO v2.x will rename or remove IDs that are referenced by <use> elements in separate SVG files. This occurs because SVGO processes each file as an isolated unit; it has no native mechanism to track references across a project or maintain a global symbol table.

Why References Break

When cleanupIDs analyzes a file, it checks if an ID is referenced within that specific document. If an ID is only referenced by an external file (e.g., <use href="sprite.svg#icon-home">), the plugin views that ID as unreferenced. Consequently, it may rename icon-home to a generic string like a to reduce file size, breaking the link in the external file.

How to Preserve Original IDs

To prevent the plugin from renaming IDs that must remain stable for external references, you must explicitly exclude them from the cleanup process. Use the preserveIds option within the plugin configuration:

{
  "plugins": [
    {
      "name": "cleanupIDs",
      "params": {
        "preserveIds": true
      }
    }
  ]
}

Setting preserveIds: true instructs the plugin to keep the original IDs intact, ensuring that external <use> references continue to resolve correctly.

Verification Steps

To verify this behavior in your environment, perform the following test:

1. Create source.svg with an element id="test-id".
2. Create main.svg with <use href="source.svg#test-id">.
3. Run SVGO on source.svg with cleanupIDs enabled.
4. Check if test-id was renamed. If it was, the reference in main.svg is now broken.

Note on Configuration Errors

The error Invalid configuration: plugins must be an array is a schema validation failure. It indicates that the plugins key in your config is likely a string or an object rather than a list (e.g., "plugins": "cleanupIDs" instead of "plugins": ["cleanupIDs"]). This is a syntax issue and is unrelated to the logical behavior of the ID cleanup process.

Diagnostic Detail: Are you using a custom regex for preserveIds or a boolean? If using a regex, please provide the pattern to ensure it matches your ID naming convention.