svg/svgo v4.0.0-rc.2

on GitHub

I apologize for the wait, and I appreciate everyone's patience! It's been some time since the last release candidate as I was very busy with client work. ^-^'

Release Candidate

This is a release candidate. We are still working on v4.0.0, and API stability isn't guaranteed, though we'll aim to keep it fairly consistent. You can try this build by installing or depending on svgo@4.0.0-rc.2, or svgo@rc.

Please report any problems you encounter in the GitHub issue tracker. 👍

Refer to the release notes of previous v4.0.0 release candidates to get the full context, this will only describe the differences since the previous release candidate.

We're also working on a Migration Guide from v3 to v4. This will be accessible on svgo.dev once SVGO v4 has been officially released, but currently can only be read from the repository. The migration guide is more concise than the release notes, and only covers the breaking changes.

Changes

This release mostly sets out to resolve issues reported regarding v4.0.0-rc.1. There was a mistake with our type declarations, that led to named exports like optimize to not be handled correctly.

I've amended the project to move away from manually maintained type declaration files, to generating our type declarations using tsc based on our JSDoc types and local types. This should guarantee that our type declarations will be up-to-date with our implementation from now on.

Breaking Changes

Default Export

This release drops default exports from the library. My original plan was to keep them in SVGO v4, and export with both named and default exports. However, this seems a little more annoying to maintain than I was expecting.

If you are using the import syntax and imported SVGO via the default export, then you must adapt your code for v4:

- import svgo from 'svgo';
- svgo.optimize('<svg></svg>');

// Option 1. Use named exports!
+ import { optimize } from 'svgo';
+ optimize('<svg></svg>');

// Option 2. Or import everything as svgo!
+ import * as svgo from 'svgo';
+ svgo.optimize('<svg></svg>');

This has no impact on users who:

• Use SVGO from the CLI.
• Import the project from CJS (require).
• Who were already using named exports when importing SVGO.

If you'd like more details on the reason, please see: #2118

Selector Helpers

The XastNode#parentNode property was declared legacy and pending removal for v4, but was still used internally. The remaining instances have now been removed, which required a refactor of the selector helpers.

This effects custom plugins that use any of the following functions, where the selector (2nd) argument could reference parent or sibling nodes (i.e. div > span):

• querySelectorAll
• querySelector
• matches

Previously, these functions had the context of the whole node tree, even if a child node was passed to it. It no longer has that context by default. The new API for these functions are as follows:

// applies `selector` with the context of the `childNode` and its descendants
const nodes = querySelectorAll(childNode, selector);

// applies `selector` with the context of the entire node tree relative from `childNode`
// the `rootNode` is required if the result of `selector` may depend on the parent or sibling of `childNode`
const nodes = querySelectorAll(childNode, selector, rootNode);

// this usage has the same behavior as v3, as `rootNode` is already the entire node tree 
const nodes = querySelectorAll(rootNode, selector);

A helper has been provided named #mapNodesToParents, which does this for you. This can be used to easily migrate to the new API. If you're not sure if you need it, then it's safer to take this approach. The third argument won't be necessary if selector does not traverse nodes, for example querying using one or more attributes of a single node.

- import { querySelectorAll } from 'svgo';
+ import { querySelectorAll, mapNodesToParents } from 'svgo';

- const nodes = querySelectorAll(childNode, selector);
+ const nodes = querySelectorAll(childNode, selector, mapNodesToParents(rootNode));

Metrics

No functional changes have been made that would affect SVG optimization.

Before and after of the browser bundle of each respective version: