Skip to content

Commit a9d27df

Browse files
SethFalcoSethFalco
authored
docs: write v2 to v3 migration guide (#2177)
1 parent 35969bc commit a9d27df

File tree

3 files changed

+175
-22
lines changed

3 files changed

+175
-22
lines changed

‎docs/06-migrations/01-migration-from-v3-to-v4.mdx‎

Lines changed: 22 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,20 @@
22
title: Migration from v3 to v4
33
---
44

5-
This is a summary of the changes necessary to migrate from SVGO v3 to SVGO v4. If you want more details or have any questions, please refer to our [release notes for SVGO v4.0.0](https://github.com/svg/svgo/releases/tag/v4.0.0) or related pull requests. You're also encouraged to leave comments in pull requests if the existing content doesn't already answer your question.
5+
This is a summary of the changes necessary to migrate from SVGO v3 to SVGO v4. If you want more details or have any questions, please refer to our [release notes for SVGO v4.0.0](https://github.com/svg/svgo/releases/tag/v4.0.0) or related pull requests. You're encouraged to leave comments in pull requests if the existing content doesn't answer your question.
66

77
## Version Requirements
88

9-
SVGO now requires [Node.js >=16.0.0](https://nodejs.org/en/blog/release/v16.0.0).
9+
SVGO now requires [Node.js >=16.0.0](https://nodejs.org/blog/release/v16.0.0).
1010

1111
## Default Behavior
1212

13-
The following changes have been made to default plugins, also known as [preset-default](/docs/preset-default/).
13+
The following changes have been made to default plugins, also known as [preset-default](/docs/preset-default/):
1414

15-
- **[removeViewBox](/docs/plugins/removeViewBox/)** is no longer a default plugin, to preserve scalability.
16-
- **[removeTitle](/docs/plugins/removeTitle)** is no longer a default plugin, to preserve accessibility.
17-
- **removeScriptElement** has been renamed to **[removeScripts](/docs/plugins/removeScripts)**, as it not only removes the `<script>` element, but also event handlers, and script URIs.
15+
- **[removeViewBox](/docs/plugins/removeViewBox/)** is no longer a default plugin to preserve scalability.
16+
- **[removeTitle](/docs/plugins/removeTitle)** is no longer a default plugin to preserve accessibility.
1817

19-
To continue using removeViewBox or removeTitle, configure it in the SVGO config, see the [README](https://github.com/svg/svgo?tab=readme-ov-file#configuration) for more context, but please consider reading the warnings in the respective plugin's documentation first:
18+
To continue using removeViewBox or removeTitle, configure it in the SVGO config. See the [README](https://github.com/svg/svgo?tab=readme-ov-file#configuration) for more context, but please consider reading the warnings in the respective plugin's documentation first:
2019

2120
```diff
2221
export default {
@@ -28,7 +27,9 @@ To continue using removeViewBox or removeTitle, configure it in the SVGO config,
2827
};
2928
```
3029

31-
If you were using the removeScriptElement plugin, amend your SVGO config to use removeScripts instead:
30+
## Plugins
31+
32+
The removeScriptElement plugin has been renamed to **[removeScripts](/docs/plugins/removeScripts)**, as it not only removes the `<script>` element but also event handlers and script URIs. If you were using the removeScriptElement plugin, amend your SVGO config to use removeScripts instead:
3233

3334
```diff
3435
export default {
@@ -40,9 +41,9 @@ If you were using the removeScriptElement plugin, amend your SVGO config to use
4041
};
4142
```
4243

43-
## Public vs Internal API
44+
## Public vs. Internal API
4445

45-
We now enforce a boundary between public and internal API. It's no longer possible to arbitrarily import any code declared by SVGO, but rather only the public API we declare as part of our semantic versioning.
46+
We now enforce a boundary between public and internal APIs. It's no longer possible to arbitrarily import any code declared by SVGO, but rather only the public API we declare as part of our semantic versioning.
4647

4748
There are two ways to import SVGO:
4849

@@ -83,45 +84,44 @@ const pluginMap = builtinPlugins.reduce((acc, val) => acc.set(val.name, val), ne
8384

8485
### Selector Helpers
8586

86-
Xast/CSS helpers for selecting nodes must be imported from `svgo` instead, and have different behavior. 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`):
87+
Xast/CSS helpers for selecting nodes must be imported from `svgo` instead and have different behavior. This affects custom plugins that use any of the following functions, where the `selector` (2nd) argument could reference parent or sibling nodes (i.e. `div > span`):
8788

8889
- `querySelectorAll`
8990
- `querySelector`
9091
- `matches`
9192

9293
If this applies to you, then you need to pass a `Map` of nodes to their parent node as a third argument.
9394

94-
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.
95+
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` doesn't traverse nodes. For example, querying using one or more attributes of a single node.
9596

9697
```diff
9798
- import { querySelectorAll } from 'svgo';
9899
- const nodes = querySelectorAll(childNode, selector);
99-
100100
+ import { querySelectorAll, mapNodesToParents } from 'svgo';
101101
+ const nodes = querySelectorAll(childNode, selector, mapNodesToParents(rootNode));
102102
```
103103

104-
The new API for these functions are as follows:
104+
The new API for these functions is as follows:
105105

106106
```js
107-
// applies `selector` with the context of the `childNode` and its descendants
107+
// applies `selector` with context of the `childNode` and its descendants
108108
const nodes = querySelectorAll(childNode, selector);
109109

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

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

118-
## Named vs Default Exports
118+
## Named vs. Default Exports
119119

120-
SVGO now only has named exports, there are no default exports in the public API.
120+
SVGO now only has named exports—there are no default exports in the public API.
121121

122-
If you use SVGO from the CLI, or have a Common JS project (you import SVGO using `require`), or if you were already using named exports, you don't have to do anything.
122+
If you use SVGO from the CLI, have a Common JS project (you import SVGO using `require`), or are already using named exports, you don't have to do anything.
123123

124-
If one way or another you're using the `import` keyword to import SVGO, then any instance where you use a default export must be switched for the named equivilent.
124+
If one way or another you're using the `import` keyword to import SVGO, then any instance where you use the default export must be replaced with the named equivalent.
125125

126126
```diff
127127
- import svgo from 'svgo';

‎docs/06-migrations/02-migration-from-v2-to-v3.mdx‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
title: Migration from v2 to v3
3+
---
4+
5+
This is a summary of the changes necessary to migrate from SVGO v2 to SVGO v3. If you want more details or have any questions, please refer to our [release notes for SVGO v3.0.0](https://github.com/svg/svgo/releases/tag/v3.0.0).
6+
7+
## Version Requirements
8+
9+
SVGO now requires [Node.js >=14.0.0](https://nodejs.org/blog/release/v14.0.0).
10+
11+
## Default Behavior
12+
13+
The **[sortAttrs](/docs/plugins/sortAttrs)** plugin is now enabled by default to improve gzip compression.
14+
15+
To disable this behavior, configure it in the SVGO config. See the [README](https://github.com/svg/svgo?tab=readme-ov-file#configuration) for more context.
16+
17+
```diff
18+
export default {
19+
plugins: [
20+
- 'preset-default',
21+
+ {
22+
+ name: 'preset-default',
23+
+ params: {
24+
+ overrides: {
25+
+ sortAttrs: false,
26+
+ },
27+
+ },
28+
+ },
29+
],
30+
};
31+
```
32+
33+
## Plugins
34+
35+
The cleanupIDs plugin has been renamed to **[cleanupIds](/docs/plugins/cleanupIds)** to bring more consistency between plugin names. If you were using cleanupIDs explicitly, amend your SVGO config to use cleanupIds instead:
36+
37+
```diff
38+
export default {
39+
plugins: [
40+
- 'cleanupIDs',
41+
+ 'cleanupIds',
42+
],
43+
};
44+
```
45+
46+
The cleanupIds plugin no longer accepts the `prefix` parameter. Use the **[prefixIds](/docs/plugins/prefixIds)** plugin instead. You must put prefixIds **_after_** cleanupIds. Doing so the other way around would just remove the prefixes again.
47+
48+
```diff
49+
export default {
50+
plugins: [
51+
{
52+
name: 'cleanupIds',
53+
- params: {
54+
- prefix: 'my-prefix',
55+
- },
56+
},
57+
+ {
58+
+ name: 'prefixIds',
59+
+ params: {
60+
+ prefix: 'my-prefix',
61+
+ },
62+
+ },
63+
]
64+
}
65+
```
66+
67+
## Configuration
68+
69+
### Active Plugins
70+
71+
Plugins defined in the `plugins` array no longer accept the property `active`. A plugin is enabled if it is named, and disabled if it is not named. Remove these entries from your config outright if you do not want them enabled.
72+
73+
```diff
74+
export default {
75+
plugins: [
76+
{
77+
name: 'removeDoctype',
78+
- active: true,
79+
},
80+
- {
81+
- name: 'removeComments',
82+
- active: false,
83+
- },
84+
],
85+
}
86+
```
87+
88+
### Overriding Default Plugins
89+
90+
The `extendDefaultPlugins` helper utility has been removed. You can disable plugins that are enabled by default in `preset-default` through the `override` parameter instead.
91+
92+
```diff
93+
- import { extendDefaultPlugins } from 'svgo';
94+
95+
export default {
96+
- plugins: extendDefaultPlugins([
97+
- {
98+
- name: 'collapseGroups',
99+
- active: false,
100+
- },
101+
- ]),
102+
+ plugins: [
103+
+ {
104+
+ name: 'preset-default',
105+
+ params: {
106+
+ overrides: {
107+
+ collapseGroups: false,
108+
+ },
109+
+ },
110+
+ },
111+
+ ],
112+
}
113+
```
114+
115+
## JavaScript API
116+
117+
We've removed the `info` property from the optimization result. This means we no longer return a width and height of the SVG. We've also removed `error` and `modernError` from the optimization result. All exceptions are thrown to the caller.
118+
119+
```diff
120+
- const {data, error, modernError } = optimize(svg)
121+
+ try {
122+
+ const { data } = optimize(svg)
123+
+ } catch (error) {
124+
+ if (error.name === 'SvgoParserError') {
125+
+ error.toString(); // formatted error
126+
+ } else {
127+
+ // other runtime error
128+
+ }
129+
+ }
130+
```
131+
132+
## Custom Plugins
133+
134+
We previously supported different types of plugins: `full`, `perItem`, `perItemReverse`, and `visitor`.
135+
136+
We now only support the `visitor` plugin API. Any other type would need to be migrated to it. See the [Plugin Architecture documentation](/docs/plugins-api) for more information.
137+
138+
## TypeScript
139+
140+
SVGO now bundles TypeScript declarations in the npm package. There is no need to install `@types/svgo` separately. This does not affect users that never depended on `@types/svgo` directly or indirectly. You can check your lockfile to be sure.
141+
142+
If you depended on `@types/svgo` before, uninstall it:
143+
144+
```sh
145+
# npm
146+
npm uninstall @types/svgo
147+
148+
# Yarn
149+
yarn remove @types/svgo
150+
```

‎rollup.config.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,9 @@ const terserOptions = {
2929
},
3030
};
3131

32+
/**
33+
* @type {import('rollup').RollupOptions[]}
34+
*/
3235
export default [
3336
{
3437
input: './lib/svgo-node.js',

0 commit comments

Comments
 (0)