feat: add experimetal svgo docs #12637

azat-io · 2025-10-28T18:03:10Z

Description (required)

Adds documentation for the new experimental SVG optimization feature.

Related to: withastro/astro#13880

Added new page at /reference/experimental-flags/svg/
Includes configuration examples and common use cases
Documents SVGO integration and error handling

Related issues & labels (optional)

N/A.

netlify · 2025-10-28T18:03:16Z

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`a04876b`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6909c7e70c22e70008fbbc1d
😎 Deploy Preview	https://deploy-preview-12637--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

astrobot-houston · 2025-10-28T18:03:39Z

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/reference/experimental-flags/svg-optimization.mdx	Localization added, will be marked as complete.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

sarah11918

Thanks for this docs PR @azat-io ! It's wonderfully well-written and a pleasure to read!

I made some initial comments/thoughts here, because I still want some questions answered in the other PR first before we look at this one too closely. Just want to make sure we're clear on the feature before we hit the docs too hard, but it's now a work in progress! 🙌

sarah11918 · 2025-10-29T11:39:37Z

astro.sidebar.ts

 					'reference/experimental-flags/static-import-meta-env',
 					'reference/experimental-flags/chrome-devtools-workspace',
 					'reference/experimental-flags/fail-on-prerender-conflict',
+					'reference/experimental-flags/svg',


Suggested change

'reference/experimental-flags/svg',

'reference/experimental-flags/svg-optimization',

Even if the experimental flag name doesn't change, this page should still be precisely named because we have other docs content about SVGs in general. (And, this will mean updating the file name of the reference page!)

Done ✅️️️️

sarah11918 · 2025-10-29T12:01:56Z

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx

+
+## Usage
+
+Once enabled, SVG optimization will automatically apply to all SVG files imported in your project:


Question: does this work if you import SVGs, but then use an <svg> element? Or does this only work if you happen to use the SVG component pattern shown below? Is it more about any imported file, or does it further depend on how it's used?

This is for components

sarah11918 · 2025-10-29T12:05:14Z

src/content/docs/en/reference/experimental-flags/svg.mdx

+
+SVG optimization happens during the build process, not at runtime. This means:
+
+- **Development:** SVGs are not optimized during development for faster rebuild times


This doesn't feel like a cohesive list of three related things: dev, prod, then... something else? And not sure Performance Considerations will be the right heading, since that implies "Things you have to think about to manage performance" but really, this is just "how it works." Will think about this one!

Done ✅️️️️

sarah11918 · 2025-10-29T12:06:58Z

src/content/docs/en/reference/experimental-flags/svg.mdx

+
+The optimization process can increase build times slightly, but results in smaller file sizes and faster page loads for your users.
+
+## Migration notes


I don't think this section is necessary at all. This is how all experimental features go, and most importantly, we don't want to call our shot by guessing what this feature will look like by the time it's stable.

(If you look at my comments in the implementation PR, I'm still not even sure how it will look when the PR merges! 😂 )

Done ✅️️️️

sarah11918 · 2025-10-30T09:47:26Z

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx

+        plugins: [
+          'preset-default',
+          {
+            name: 'removeHiddenElems',


I'm curious why this is required here, since looking at SVGO's docs, removeHiddenElems is included in preset-default. So why do we specifically need to mention and make this active?

Also from looking at their documentation, they show using preset-default to get that entire list by default (and then remove as you like) OR adding only individual plugins in an array. Does your feature have something comparable? Does it work if the plugins array is just a list of the individual plugins you do want, and does not include preset-default?

We should have under ### svgoConfig a #### plugins reference entry in either case, something like:

plugins

(type signature stuff)
An array of [SVGO plugins](link to all the plugins) that will be used to optimize your SVG component imports.

This can include any plugins by ID name, including SVGO's preset-default collection of plugins. A plugin can optionally be passed as an object including both its name and active status, to enable or disable as necessary.

Then, here is also where we need to explain any other options that are not passed in the plugins array:

Other configuration options

You can also pass [other SVGO configuration options](ideally a link to where we can see these??), such as floatingPoint and ..., directly to your config object.

sarah11918 · 2025-10-30T09:58:13Z

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx

+
+Configuration object passed directly to SVGO for customizing SVG optimization.
+
+See [SVGO documentation](https://svgo.dev/docs/preset-default/) for available options and plugins.


This link only appears to go to information about the preset-default and not plugins in general, nor any other available options. So, I'm wondering if https://svgo.dev/docs/plugins/ is maybe a better link to lead people to for plugins info.

This allows you to further control Astro's SVG optimization with [SVGO plugins](https://svgo.dev/docs/plugins/).

And also, I'm not sure exactly how to describe these "other options." Later, you show using floatPrecision outside of the plugins array and it's not obvious where that comes from, or what else is available to use. (Is that maybe how you pass paramaters to a plugin? In the SVGO documentation, it appears that floatPrecision is a parameter of a plugin, and not a separate thing itself.)

sarah11918 · 2025-10-30T10:00:22Z

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx

+    svg: {
+      optimize: true,
+      svgoConfig: {
+        floatPrecision: 2


As mentioned above, this svgoConfig option appears to come out of nowhere. Is there a definitive list of everything you can pass to svgoConfig? This example shows no SVGO plugins being used at all, but I can't find in SVGO documentation a list of options that you can configure that are not related to plugins. We would need to document for people above in the svgoConfig section all the options you can pass to it.

sarah11918 · 2025-10-30T10:19:09Z

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx

+## Further reading
+
+- [SVGO documentation](https://svgo.dev/)
+- [SVGO preset-default plugins](https://svgo.dev/docs/preset-default/)


Suggested change

- [SVGO preset-default plugins](https://svgo.dev/docs/preset-default/)

Since we'll mention above a link to plugins in context, I think just the main documentation link is fine here.

sarah11918

Thanks for the further clarifications and updates!

I've left already a handful of comments below for some reworking of the page here for your consideration.

Also, given that this works only for SVG components, in general, let's use the term "SVG component imports" instead of "SVG imports." This avoids the question of whether this does anything for SVG's not used specifically as components. (For example, people might wonder about using this with UI framework components, but the SVG component pattern is only for Astro components.)

I know below is a lot, so I'm going to stop now and let you look over it all! 😄

sarah11918 · 2025-10-30T10:20:11Z

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx

+<Since v="5.8.0" />
+</p>
+
+This experimental feature enables automatic optimization of SVG assets using [SVGO](https://svgo.dev/) during build time.


Suggested change

This experimental feature enables automatic optimization of SVG assets using [SVGO](https://svgo.dev/) during build time.

This experimental feature enables automatic optimization of your [SVG components](/en/guides/images/#svg-components) using [SVGO](https://svgo.dev/) during build time.

Just checking that this is true? Even without the svgoConfig object, SVGO is being used?

Also, making it clear that this feature is associated specifically with SVG components!

sarah11918 · 2025-10-30T10:27:58Z

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx

+
+This experimental feature enables automatic optimization of SVG assets using [SVGO](https://svgo.dev/) during build time.
+
+When enabled, all imported SVG files will be optimized for smaller file sizes and better performance while maintaining visual quality. This can significantly reduce the size of your SVG assets by removing unnecessary metadata, comments, and redundant code.


Suggested change

When enabled, all imported SVG files will be optimized for smaller file sizes and better performance while maintaining visual quality. This can significantly reduce the size of your SVG assets by removing unnecessary metadata, comments, and redundant code.

When enabled, your imported SVG files used as components will be optimized for smaller file sizes and better performance while maintaining visual quality. This can significantly reduce the size of your SVG assets by removing unnecessary metadata, comments, and redundant code.

sarah11918 · 2025-10-30T10:31:00Z

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx

+
+## Usage
+
+Once enabled, SVG optimization will automatically apply to all SVG files imported in your project:


Suggested change

Once enabled, SVG optimization will automatically apply to all SVG files imported in your project:

No change to using SVG components is required to take advantage of this feature. With experimental `svg.optimization` enabled, all your SVG component import files will be automatically optimized:

sarah11918 · 2025-10-30T10:33:05Z

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx

+<Logo />
+```
+
+The SVG will be optimized during the build process, resulting in smaller file sizes in your production build.


Suggested change

The SVG will be optimized during the build process, resulting in smaller file sizes in your production build.

If SVGO optimization fails for any reason, Astro will gracefully fall back to using the original, unoptimized SVG content. A warning will be logged to the console, but your build will continue without errors.

Note that this optimization applies to every SVG component import in your project. It is not possible to opt out on a per-component basis.

The previous line was true, but already said! Since this section is focused on usage, we'd try to anticipate questions people might have about using it in their project. Like for example, can this be done on a per-component basis? (I'm assuming no, so I've written the above.) If you can think of any other kinds of questions people might have, this would be a good place to inform them of specific usage tips and tricks!

I don't think we need a specific heading about error handling because that implies there's something for people do to handle errors, vs just "here's what happens in case of an error." I think this content fits better right in here.

sarah11918 · 2025-10-30T10:39:41Z

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx

+## Error handling
+
+If SVGO optimization fails for any reason, Astro will gracefully fall back to using the original, unoptimized SVG content. A warning will be logged to the console, but your build will continue without errors.
+


Suggested change

## Error handling

If SVGO optimization fails for any reason, Astro will gracefully fall back to using the original, unoptimized SVG content. A warning will be logged to the console, but your build will continue without errors.

Suggest removing in favour of this line moving up into ## Usage I think!

sarah11918 · 2025-10-30T10:42:53Z

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx

+})
+```
+
+## Configuration


I'd like to see this entire configuration section move down below ## Usage so that people can immediately see "enable, then here's what affect it has on my existing project." I feel like a lot of people might turn this on and use it, then figure out whether they need or want to tweak customization later, so I think gets important information about what this means for your project and existing code up earlier!

It feels like a good flow here would be:

## Overview ## Usage ## Configuration ### optimize ### SVGO config ## Common Use Cases (sub-headings) ## How it works ## Further Reading (maybe optional even? We already link to both the main and the docs site from this page. A *good* addition here could be if you know of a really awesome/canonical article on optimizing SVGs.)

sarah11918 · 2025-10-30T10:52:29Z

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx

+
+The SVG will be optimized during the build process, resulting in smaller file sizes in your production build.
+
+## Common use cases


Suggested change

## Common use cases

## Common use cases

SVGO provides an extensive [default plugin list](https://svgo.dev/docs/preset-default/) with opinionated optimizations that is more convenient than adding each plugin individually. However, you may need to customize it further for your needs. For example, it may remove items or clean up too aggressively for your situation.

We always prefer to have some text after a heading to explain what this section will focus on. So, I just invented the above which you are welcome to make accurate, but something like this should go here.

sarah11918 · 2025-10-30T10:53:15Z

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx

+
+### Preserve specific attributes
+
+You may want to preserve certain SVG attributes that SVGO removes by default:


Suggested change

You may want to preserve certain SVG attributes that SVGO removes by default:

You may want to preserve certain SVG attributes, such as the `viewBox`, that SVGO removes by default:

Is this correct to say?

azat-io · 2025-10-30T17:24:01Z

Restructured document: moved Usage before Configuration
Updated terminology: "SVG assets" → "SVG components" with link to guide
Enhanced Usage section: added error handling info, noted no per-component opt-out
Added svgoConfig documentation: plugins subsection and other options subsection
Updated SVGO link: from preset-default to general plugins page
Enhanced "Common use cases": added intro paragraph, replaced removeHiddenElems with removeMetadata
Simplified "Further reading": removed redundant links

sarah11918 · 2025-10-31T06:02:30Z

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx

+
+#### Other configuration options
+
+You can also pass [other SVGO configuration options](https://svgo.dev/docs/configuration/), such as `floatPrecision` and `multipass`, directly to your config object:


This is exactly what I'd want, but the link is 404'ing. So we'll need to find wherever this full configuration is listed! We prefer not to, but if we have to, we can even link to a file/specific lines in their repo where these options are listed. A docs link is better, but we absolutely need to make sure people can find what these options are, one way or another!

sarah11918 · 2025-10-31T06:03:41Z

This looks fantastic @azat-io , thank you! Just one broken link here, as mentioned, but then I think this is great!

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx

Co-authored-by: Sarah Rainsberger <[email protected]>

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx

sarah11918 · 2025-11-04T10:19:50Z

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx

+
+The SVG will be optimized during the build process, resulting in smaller file sizes in your production build.
+
+If SVGO optimization fails for any reason, Astro will gracefully fall back to using the original, unoptimized SVG content. A warning will be logged to the console, but your build will continue without errors.


@florian-lefebvre Whatever we decide in withastro/astro#13880 , needs to match here too!

feat: add experimetal svgo docs

b069776

azat-io mentioned this pull request Oct 28, 2025

feat: add SVGO optimization support for SVG assets withastro/astro#13880

Open

sarah11918 reviewed Oct 29, 2025

View reviewed changes

sarah11918 added this to the v6.0.0 docs milestone Oct 29, 2025

refactor: make fixes by review

81749d7

sarah11918 reviewed Oct 30, 2025

View reviewed changes

refactor: make fixes by review

4fc5050

sarah11918 reviewed Oct 31, 2025

View reviewed changes

azat-io added 2 commits October 31, 2025 20:33

fix: fix svgo configuration link

4ed24b9

feat: use new svgo config format

3005899

sarah11918 reviewed Nov 3, 2025

View reviewed changes

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx Outdated Show resolved Hide resolved

refactor: update link to svgo options

a2728a8

Co-authored-by: Sarah Rainsberger <[email protected]>

sarah11918 reviewed Nov 3, 2025

View reviewed changes

src/content/docs/en/reference/experimental-flags/svg-optimization.mdx Outdated Show resolved Hide resolved

update version number for the feature

a04876b

sarah11918 added the minor-release For the next minor release; in the milestone, "merge queue" when approved by Sarah! label Nov 4, 2025

sarah11918 modified the milestones: v6.0.0 docs, 5.16.0 Nov 4, 2025

sarah11918 reviewed Nov 4, 2025

View reviewed changes

	'reference/experimental-flags/svg',
	'reference/experimental-flags/svg-optimization',


		## Usage

		Once enabled, SVG optimization will automatically apply to all SVG files imported in your project:


		SVG optimization happens during the build process, not at runtime. This means:

		- Development: SVGs are not optimized during development for faster rebuild times


		The optimization process can increase build times slightly, but results in smaller file sizes and faster page loads for your users.

		## Migration notes


		Configuration object passed directly to SVGO for customizing SVG optimization.

		See [SVGO documentation](https://svgo.dev/docs/preset-default/) for available options and plugins.

	This experimental feature enables automatic optimization of SVG assets using [SVGO](https://svgo.dev/) during build time.
	This experimental feature enables automatic optimization of your [SVG components](/en/guides/images/#svg-components) using [SVGO](https://svgo.dev/) during build time.


		This experimental feature enables automatic optimization of SVG assets using [SVGO](https://svgo.dev/) during build time.

		When enabled, all imported SVG files will be optimized for smaller file sizes and better performance while maintaining visual quality. This can significantly reduce the size of your SVG assets by removing unnecessary metadata, comments, and redundant code.

	When enabled, all imported SVG files will be optimized for smaller file sizes and better performance while maintaining visual quality. This can significantly reduce the size of your SVG assets by removing unnecessary metadata, comments, and redundant code.
	When enabled, your imported SVG files used as components will be optimized for smaller file sizes and better performance while maintaining visual quality. This can significantly reduce the size of your SVG assets by removing unnecessary metadata, comments, and redundant code.

	Once enabled, SVG optimization will automatically apply to all SVG files imported in your project:
	No change to using SVG components is required to take advantage of this feature. With experimental `svg.optimization` enabled, all your SVG component import files will be automatically optimized:

		## Error handling

		If SVGO optimization fails for any reason, Astro will gracefully fall back to using the original, unoptimized SVG content. A warning will be logged to the console, but your build will continue without errors.


		The SVG will be optimized during the build process, resulting in smaller file sizes in your production build.

		## Common use cases


		### Preserve specific attributes

		You may want to preserve certain SVG attributes that SVGO removes by default:


		#### Other configuration options

		You can also pass [other SVGO configuration options](https://svgo.dev/docs/configuration/), such as `floatPrecision` and `multipass`, directly to your config object:

Uh oh!

feat: add experimetal svgo docs #12637

Are you sure you want to change the base?

feat: add experimetal svgo docs #12637

Conversation

azat-io commented Oct 28, 2025

Description (required)

Related issues & labels (optional)

Uh oh!

netlify bot commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-docs-2 ready!

Uh oh!

astrobot-houston commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Lunaria Status Overview

Tracked Files

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sarah11918 Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

plugins

Other configuration options

Uh oh!

sarah11918 Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

azat-io commented Oct 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sarah11918 commented Oct 31, 2025

Uh oh!

Uh oh!

Uh oh!

netlify bot commented Oct 28, 2025 •

edited

Loading

astrobot-houston commented Oct 28, 2025 •

edited

Loading

sarah11918 Oct 30, 2025 •

edited

Loading

`plugins`

sarah11918 Oct 30, 2025 •

edited

Loading