feat(astro): add Built-in SVG component support #12067

stramel · 2024-09-25T04:40:21Z

Changes

This PR implements Built-in SVG Components following up on the discussions on withastro/roadmap#699

By default, SVG files will be components and can be imported by referencing their file path and then treating them like a component. Take this for example:

previously:

---
import Image from 'astro:assets'
import logo from './path/to/svg/file.svg'
---

<div set:html={logo}  style={{height: '24px', width: '24px' }} />
<!-- or -->
<Image src={logo} width={24} height={24} />

now:

---
import Logo from './path/to/svg/file.svg';
---

<Logo size={24} />

GOALS:

Allow users to import and render local .svg files as if they were an Astro component
Allow passing props onto the root <svg> element while overriding the existing props
Automate best practices for to minimize performance footguns
- Including many inlined <svg> on a page can hurt browser parsing performance. We can automatically reduce the number of nodes by using <symbol> and <use>.
- Inline <svg> often have xmlns and xmlns:xlink and version attributes. These are not needed in HTML5 and we can automatically drop them to save a few bytes.
Support this in a backwards-compatible way, meaning the current public interface of an .svg import remains unchanged
Stretch: support rendering .svg components in frameworks without inlining them into the client side JavaScript
- Creating framework components for .svg icons is an anti-pattern. It’s a terrible idea that bloats your JavaScript and creates all sorts of headaches for HMR and clientside performance in production.
- If we provide a great <Icon> component for each supported framework, we’ll make it easy for users to avoid this anti-pattern. It’s so common now because there aren’t many other good solutions.

This builds a foundation for us which can be extended in the future within the core astro and even by third-parties. For instance using astro-icon, which has been the critical plugin when it comes to icons, as a playground, I was able to extend the foundation built here to add dynamic icon import for Iconify.

FUTURE:

Optimization: Allow hooking in SVGO or other SVG Optimizers

/cc @natemoo-re

Testing

I have ensured that existing tests are functioning properly and added additional suite for SVG Components.

Manually, I have updated the blog example to include using the SVG components. I have also tested locally against astro-icon and its demo application. Will work on some testing for this change.

Docs

Docs added in withastro/docs#9911

changeset-bot · 2024-09-25T04:40:27Z

🦋 Changeset detected

Latest commit: 7b4a3a9

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions

This PR is blocked because it contains a major changeset. A reviewer will merge this at the next release if approved.

natemoo-re

Left a few suggestions, but this looks really good!

natemoo-re · 2024-09-30T12:01:53Z

packages/astro/client.d.ts

+		/**
+		 * Bypasses automatic sprite optimization by directly inlinining the SVG
+		 */
+		inline?: boolean


After sitting with this for a while, inline behavior should be the default. There are a few edge-cases that have come up with dynamic client-side behavior in astro-icon, so while I still think the optimization is very useful, we should prioritize flexibility by keeping the sprite behavior opt-in.

You're right. I think especially with the SVG imports that developers wouldn't necessarily assume the optimization by default.

My first thought is to offer a "mode" that allows for "sprite" or "inline" ("inline" being the default) that is configurable in the Astro Config. I assume we'll later have some other properties under and "svg" scope such as an "image service" (like svgo).

I have also seen an interesting use-case (natemoo-re/astro-icon#238) that we might be able to support later for exporting symbols instead. This would be fairly trivial with a "mode" and might enable some better DX around framework usages.

I would like to discuss and perhaps iterate a bit on the way we allow developers to opt-in/out of inline/sprite usages. Will bring this up in the Stage 3 RFC.

packages/astro/src/assets/runtime.ts

natemoo-re · 2024-09-30T12:05:31Z

packages/astro/src/assets/utils/node/emitAsset.ts

+	// Attach file data for SVGs
+	if (fileMetadata.format === 'svg') {
+		emittedImage.contents = fileData;
+	}


Would love @Princesseuh's take on this. Any expected footguns with including the file content for SVGs in the image metadata?

If you have a lot of SVGs, this can be problematic for SSR since it'll get in your bundle, that's my only concerns

Right. Unfortunately that will be unavoidable for this feature.

I think the DX improvement is worth the tradeoff, though!

This is definitely outside my realm of expertise. I'll defer to whatever the consensus is here :)

Something we could do one day (definitely outside of this PR), though it'd make SVG icons somewhat slower in SSR is add a lazy data property or something, that's essentially async () => await fetch(this.src) in SSR and something else in SSG so that you can load the data without it being added to the bundle.

packages/astro/src/assets/utils/svg.ts

packages/astro/test/core-image-svg.test.js

packages/astro/test/fixtures/core-image-svg/src/assets/astro.svg

packages/astro/src/assets/utils/svg.ts

packages/astro/client.d.ts

Princesseuh · 2024-09-30T13:33:55Z

packages/astro/src/assets/utils/node/emitAsset.ts

+	// Attach file data for SVGs
+	if (fileMetadata.format === 'svg') {
+		emittedImage.contents = fileData;
+	}


If you have a lot of SVGs, this can be problematic for SSR since it'll get in your bundle, that's my only concerns

examples/blog/src/components/Footer.astro

packages/astro/src/assets/utils/svg.ts

packages/astro/src/assets/vite-plugin-assets.ts

stramel · 2024-10-05T04:31:54Z

I have added it behind an experiment flag called svg. With this change, I swapped the default implementation to be a more straightforward approach of inlining the SVG. In order to control this a bit better, I have a mode setting in the svg config to apply a default, which is defaulted to inline. I also changed the inline prop to a mode prop that will allow configuring between inline and sprite on specific SVGs.

@natemoo-re would love your opinion on this approach for configuring the sprite vs inline method

ematipico · 2024-11-06T10:41:33Z

@stramel While I was working on the PR, I noticed that you added a new configuration in Astro, which is fine, however the RFC doesn't mention anything about it. We should update the RFC and explain the options.

Also, here's some feedback regarding experimental options. There aren't written rules, but in the past I was in your same situation and I went for this route:

export default defineConfig({
	svg: {
		mode: "inline"
	},
	experimental: {
		svg: true
	}
})

We still need to have the experimental flag, which stays a boolean every time. Then, you create a new section in the Astro configuration. You're still free to change it as you see fit, because it's part of the experimental feature, however I found that the maintenance of these two separate sections is easier for us maintainers.

sarah11918

Thank you so much for this amazing feature @stramel ! I think people are going to really enjoy this! 🙌

I've done a quick pass on the documentation (changeset and flag docs) and you'll find some suggestions below for your consideration!

I know Nate has a docs PR going, and it seems like the mode property is newer than that, so we'll just make sure that we've got everything we need in the docs PR, too, before docs totally signs off on this! 🚀

.changeset/blue-socks-doubt.md

packages/astro/src/types/public/config.ts

sarah11918 · 2024-11-06T16:36:36Z

packages/astro/src/types/public/config.ts

+			 * - `inline`: Astro will inline the SVG content into your HTML output.
+			 * - `sprite`: Astro will generate a sprite sheet with all imported SVG files.
+			 * 
+			 * When using 'sprite' mode, it is important to note that the symbol definition will be included with the first instance of the SVG that is rendered. This means that if the first instance is hidden or removed from the DOM, all other references will break.


Suggested change

* When using 'sprite' mode, it is important to note that the symbol definition will be included with the first instance of the SVG that is rendered. This means that if the first instance is hidden or removed from the DOM, all other references will break.

* When using 'sprite' mode, it is important to note that the symbol definition will be included with the first instance of the SVG that is rendered. This means that if the first instance is hidden or removed from the DOM, all other references will break.

Question: is this unique to Astro's implementation, or would this be something common to using a sprite sheet in general? I get that it's a caveat, but if it's not an Astro-specific caveat then it's a little bit more for the reader to have to process before they even see how to use this feature.

I might suggest we either remove this paragraph entirely (we do say full details in the RFC!), or place it after the code example if this is a super key thing and people will have a lot of trouble using the feature if they don't know this immediately up front.

This is unique to the implementation that we chose to go with. Though it would probably apply to the spritesheet in general but is significantly less common if you just have a single spritesheet.

This is something I was debating about adding as an enhancement later or opt-in. Would need some help from the core team on it though.

I'll leave it up to you if we keep this caveat or remove it.

OK, for this stage of the game, I say we omit the caveat in these docs here. We just get people up and running quickly and happily, and they can check the RFC when and if they run into trouble!

packages/astro/src/types/public/config.ts

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

packages/astro/src/types/public/config.ts

sarah11918

Approving for docs!

(Also noting, as I always do, that I don't see any new errors added with this feature. If that changes before the feature is released, then please loop me back in! 🙌 )

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

It's ok to merge now

stramel · 2024-11-20T03:14:01Z

Thank you all for the help to get this in! I greatly appreciate all the reviews and feedback!

stramel · 2024-11-23T01:01:38Z

Seems there is some kind of issue with the refactor of ids to use WeakMap. I'm just getting all the same icon from the integration with astro-icon through the makeSvgComponent. I'll open a new PR for it

stramel · 2024-11-23T02:16:53Z

Initial fix: #12511

Going to do some testing and ensure I add a test to fail on previous case. Tested with astro-icon

github-actions bot added pkg: example Related to an example package (scope) pkg: astro Related to the core `astro` package (scope) semver: major Change triggers a `major` release labels Sep 25, 2024

github-actions bot previously requested changes Sep 25, 2024

View reviewed changes

This was referenced Sep 25, 2024

feat(core): rewrite to use built-in svg components natemoo-re/astro-icon#239

Open

Built-in SVG components withastro/roadmap#699

Closed

stramel force-pushed the add-svg-support branch 6 times, most recently from 2ff0715 to 5f8997c Compare September 25, 2024 20:43

stramel marked this pull request as ready for review September 25, 2024 21:15

natemoo-re reviewed Sep 30, 2024

View reviewed changes

Princesseuh reviewed Sep 30, 2024

View reviewed changes

Princesseuh reviewed Oct 1, 2024

View reviewed changes

examples/blog/src/components/Footer.astro Outdated Show resolved Hide resolved

stramel force-pushed the add-svg-support branch from 5f8997c to 313caaa Compare October 2, 2024 04:20

github-actions bot removed the pkg: example Related to an example package (scope) label Oct 2, 2024

stramel requested review from Princesseuh and natemoo-re October 2, 2024 04:45

Princesseuh added semver: minor Change triggers a `minor` release and removed semver: major Change triggers a `major` release labels Oct 4, 2024

Princesseuh reviewed Oct 4, 2024

View reviewed changes

packages/astro/src/assets/utils/svg.ts Outdated Show resolved Hide resolved

Princesseuh reviewed Oct 4, 2024

View reviewed changes

packages/astro/src/assets/vite-plugin-assets.ts Outdated Show resolved Hide resolved

github-actions bot added the docs pr label Oct 5, 2024

stramel requested a review from Princesseuh October 5, 2024 04:52

stramel force-pushed the add-svg-support branch 2 times, most recently from ad55d4e to bf5e98b Compare October 5, 2024 05:00

natemoo-re mentioned this pull request Nov 5, 2024

Add svg component reference withastro/docs#9911

Merged

stramel and others added 6 commits November 6, 2024 01:05

docs: update changeset

78490fb

refactor: inline functions

ddf5604

fix: make non enumerable dev only

767559c

refactor: allow boolean flag

31b08e7

docs: update documentation around experimental.svg flag

c03a467

track IDs using a WeakMap, and fix configuration types

6ab0f1a

sarah11918 reviewed Nov 6, 2024

View reviewed changes

stramel and others added 3 commits November 6, 2024 22:24

Apply suggestions from code review

d40d45d

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

refactor: swap experimental.svg schema implementation

9344a25

fix: id for svgs

28d6c38

sarah11918 reviewed Nov 12, 2024

View reviewed changes

packages/astro/src/types/public/config.ts Outdated Show resolved Hide resolved

more minimal config reference docs

676add9

sarah11918 approved these changes Nov 12, 2024

View reviewed changes

ematipico and others added 2 commits November 19, 2024 14:02

Update packages/astro/src/types/public/config.ts

08e5708

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

Merge remote-tracking branch 'origin/next' into add-svg-support

6e41401

ematipico approved these changes Nov 19, 2024

View reviewed changes

update lock file after merge

7b4a3a9

ematipico merged commit c48916c into withastro:next Nov 19, 2024
14 checks passed

astrobot-houston mentioned this pull request Nov 19, 2024

[ci] release (beta) #12430

Merged

stramel deleted the add-svg-support branch November 23, 2024 01:00

stramel mentioned this pull request Nov 23, 2024

Fix SVG Component sprite ids #12511

Merged

stramel mentioned this pull request Apr 8, 2025

feat: unflag svg component feature #13578

Merged

natemoo-re mentioned this pull request Apr 9, 2025

fix(svg): do not attach svg buffer to imageMetadata #13588

Merged

azat-io mentioned this pull request Jun 1, 2025

feat: add SVGO optimization support for SVG assets #13880

Open

	* When using 'sprite' mode, it is important to note that the symbol definition will be included with the first instance of the SVG that is rendered. This means that if the first instance is hidden or removed from the DOM, all other references will break.
	* When using 'sprite' mode, it is important to note that the symbol definition will be included with the first instance of the SVG that is rendered. This means that if the first instance is hidden or removed from the DOM, all other references will break.

Uh oh!

feat(astro): add Built-in SVG component support #12067

feat(astro): add Built-in SVG component support #12067

Uh oh!

Conversation

stramel commented Sep 25, 2024 • edited by martrapp Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Testing

Docs

Uh oh!

changeset-bot bot commented Sep 25, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

natemoo-re 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!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stramel commented Oct 5, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ematipico commented Nov 6, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

stramel commented Nov 20, 2024

Uh oh!

stramel commented Nov 23, 2024

Uh oh!

stramel commented Nov 23, 2024

Uh oh!

Reviewers

Assignees

Labels

stramel commented Sep 25, 2024 •

edited by martrapp

Loading

changeset-bot bot commented Sep 25, 2024 •

edited

Loading

stramel commented Oct 5, 2024 •

edited

Loading

ematipico commented Nov 6, 2024 •

edited

Loading