From 75dc22b4fbe2cecae0265ca3d0c18b3a3415d33f Mon Sep 17 00:00:00 2001
From: Seth Falco <seth@falco.fun>
Date: Mon, 5 May 2025 17:27:55 +0100
Subject: [PATCH] docs: add migration guide for svgo v4 (#2119)

---
 docs/01-index.mdx                             |   2 +-
 docs/02-usage/01-node.mdx                     |  27 ----
 docs/02-usage/02-browser.mdx                  |  20 ---
 ...oveScriptElement.mdx => removeScripts.mdx} |   0
 .../01-migration-from-v3-to-v4.mdx            | 138 ++++++++++++++++++
 docs/06-migrations/_category_.json            |   3 +
 6 files changed, 142 insertions(+), 48 deletions(-)
 rename docs/04-plugins/{removeScriptElement.mdx => removeScripts.mdx} (100%)
 create mode 100644 docs/06-migrations/01-migration-from-v3-to-v4.mdx
 create mode 100644 docs/06-migrations/_category_.json

diff --git a/docs/01-index.mdx b/docs/01-index.mdx
index cacacf83..71e378c8 100644
--- a/docs/01-index.mdx
+++ b/docs/01-index.mdx
@@ -11,7 +11,7 @@ SVG files, especially those exported from vector editors, usually contain a lot
 
 ### System Requirements
 
-- [Node.js 16](https://nodejs.org/) or later
+- [Node.js >=16](https://nodejs.org/)
 
 <Tabs>
   <TabItem value="npm" label="npm" default>
diff --git a/docs/02-usage/01-node.mdx b/docs/02-usage/01-node.mdx
index 25e6a39c..e73b88f2 100644
--- a/docs/02-usage/01-node.mdx
+++ b/docs/02-usage/01-node.mdx
@@ -22,30 +22,3 @@ const { data } = optimize(svg);
 console.log(data);
 // <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><text x="50" y="50" text-anchor="middle">•ᴗ•</text></svg>
 ```
-
-## Exports
-
-<dl>
-  <dt>
-    <code>VERSION</code>
-  </dt>
-  <dd>Version of SVGO during runtime.</dd>
-  <dt>
-    <code>builtinPlugins</code>
-  </dt>
-  <dd>
-    Array of built-in plugins, including plugins that are disabled by default
-    and any presets.
-  </dd>
-  <dt>
-    <code>optimize(svgCode, svgoConfig)</code>
-  </dt>
-  <dd>Invokes the optimization and returns the optimized/minified SVG code.</dd>
-  <dt>
-    <code>loadConfig(configFile, directory)</code>
-  </dt>
-  <dd>
-    Utility to find the nearest <code>svgo.config.js</code> file by searching up
-    the parent directories.
-  </dd>
-</dl>
diff --git a/docs/02-usage/02-browser.mdx b/docs/02-usage/02-browser.mdx
index 826844a8..bb553f21 100644
--- a/docs/02-usage/02-browser.mdx
+++ b/docs/02-usage/02-browser.mdx
@@ -62,23 +62,3 @@ Here's a minimal example:
   </body>
 </html>
 ```
-
-## Exports
-
-<dl>
-  <dt>
-    <code>VERSION</code>
-  </dt>
-  <dd>Version of SVGO during runtime.</dd>
-  <dt>
-    <code>builtinPlugins</code>
-  </dt>
-  <dd>
-    Array of built-in plugins, including plugins that are disabled by default
-    and any presets.
-  </dd>
-  <dt>
-    <code>optimize(svgCode, svgoConfig)</code>
-  </dt>
-  <dd>Invokes the optimization and returns the optimized/minified SVG code.</dd>
-</dl>
diff --git a/docs/04-plugins/removeScriptElement.mdx b/docs/04-plugins/removeScripts.mdx
similarity index 100%
rename from docs/04-plugins/removeScriptElement.mdx
rename to docs/04-plugins/removeScripts.mdx
diff --git a/docs/06-migrations/01-migration-from-v3-to-v4.mdx b/docs/06-migrations/01-migration-from-v3-to-v4.mdx
new file mode 100644
index 00000000..b2388f9d
--- /dev/null
+++ b/docs/06-migrations/01-migration-from-v3-to-v4.mdx
@@ -0,0 +1,138 @@
+---
+title: Migration from v3 to v4
+slug: 'migration-from-v3-to-v4'
+---
+
+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.
+
+## Version Requirements
+
+SVGO now requires [Node.js >=16.0.0](https://nodejs.org/en/blog/release/v16.0.0).
+
+## Default Behavior
+
+The following changes have been made to default plugins, also known as [preset-default](/docs/preset-default/).
+
+- **[removeViewBox](/docs/plugins/removeViewBox/)** is no longer a default plugin, to preserve scalability.
+- **[removeTitle](/docs/plugins/removeTitle)** is no longer a default plugin, to preserve accessibility.
+- **removeScriptElement** has been renamed to **[removeScripts](/docs/plugins/removeScripts)**, as it not only removes the `<script>` element, but also event handlers, and script URIs.
+
+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:
+
+```diff
+  export default {
+    plugins: [
+      'preset-default', // built-in plugins enabled by default
++     'removeViewBox',
++     'removeTitle',
+    ],
+  };
+```
+
+If you were using the removeScriptElement plugin, amend your SVGO config to use removeScripts instead:
+
+```diff
+  export default {
+    plugins: [
+      'preset-default', // built-in plugins enabled by default
+-     'removeScriptElement',
++     'removeScripts',
+    ],
+  };
+```
+
+## Public vs Internal API
+
+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.
+
+There are two ways to import SVGO:
+
+- `svgo` — for normal usage, such as scripts or server-side applications.
+- `svgo/browser` — for browser usage.
+
+### Browser Bundle
+
+If you use the browser bundle, you must amend how you import it:
+
+```diff
+- import { optimize } from 'svgo/dist/svgo.browser.js';
++ import { optimize } from 'svgo/browser';
+```
+
+### Importing Helpers or Plugins
+
+If you `import`/`require` helpers, the array of built-in plugins, or a single plugin during runtime, this is now a top-level export instead:
+
+```diff
+// import helpers
+- import { querySelector, querySelectorAll } from 'svgo/lib/xast.js';
++ import { querySelector, querySelectorAll } from 'svgo';
+
+// import the array of built-in plugins
+- import { builtin } from 'svgo/lib/builtin';
++ import { builtinPlugins } from 'svgo'
+
+// getting a single plugin
+- import presetDefault from 'svgo/plugins/preset-default';
++ import { builtinPlugins } from 'svgo';
++ const prefixDefault = builtinPlugins.find(plugin => plugin.name === 'preset-default');
+
+// getting a map of plugin names to implementations
+import { builtinPlugins } from 'svgo';
+const pluginMap = builtinPlugins.reduce((acc, val) => acc.set(val.name, val), new Map());
+```
+
+### Selector Helpers
+
+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`):
+
+- `querySelectorAll`
+- `querySelector`
+- `matches`
+
+If this applies to you, then you need to pass a `Map` of nodes to their parent node as a third argument.
+
+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.
+
+```diff
+- import { querySelectorAll } from 'svgo';
+- const nodes = querySelectorAll(childNode, selector);
+
++ import { querySelectorAll, mapNodesToParents } from 'svgo';
++ const nodes = querySelectorAll(childNode, selector, mapNodesToParents(rootNode));
+```
+
+The new API for these functions are as follows:
+
+```js
+// 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);
+```
+
+## Named vs Default Exports
+
+SVGO now only has named exports, there are no default exports in the public API.
+
+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.
+
+If one way or another you're using the `import` keyword to import SVGO, then any instance where you do use our default export, it must be switched for the named equivilent.
+
+```diff
+- 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>');
+```
diff --git a/docs/06-migrations/_category_.json b/docs/06-migrations/_category_.json
new file mode 100644
index 00000000..e9597acb
--- /dev/null
+++ b/docs/06-migrations/_category_.json
@@ -0,0 +1,3 @@
+{
+  "label": "Migrations"
+}