Compile-assets warns that fontawesome is heavy

[Yann-P]

IDK if this should be addressed or dismissed.

i'll investigate later unless someone has insights already

---

WARNING in asset size limit: The following asset(s) exceed the recommended size limit (244 KiB).
This can impact web performance.
Assets:
vendor/fontawesome/webfonts/fa-solid-900.ttf (410 KiB)
styles/pydata-sphinx-theme.css (388 KiB)
scripts/fontawesome.js (1.42 MiB)

WARNING in entrypoint size limit: The following entrypoint(s) combined asset size exceeds the recommended limit (244 KiB). This can impact web performance.
Entrypoints:
pydata-sphinx-theme (403 KiB)
styles/pydata-sphinx-theme.css
scripts/pydata-sphinx-theme.js
fontawesome (1.42 MiB)
scripts/fontawesome.js

[Yann-P]

Already 1.49 MB live on 0.17.1

so the issue was there before the recent upgrade which is not in 0.17.1, but was on my machine when I got the warning above.

[agriyakhetarpal]

Hi! I stumbled into this from the cross-link. Having worked on the upgrade, I am happy to take a look at this and investigate. :)

[agriyakhetarpal]

Here is what I could find!

root cause

The problem is that we import all.min.js in src/pydata_sphinx_theme/assets/scripts/fontawesome.js, which bundles SVG path data for thousands of icons, but we only use 32 of them (28 solid icons and 4 brands). Here is a list:

fa-solid fa-angle-left           fa-solid fa-angle-right
fa-solid fa-arrow-up             fa-solid fa-bars
fa-solid fa-bell                 fa-solid fa-chevron-down
fa-solid fa-circle-check         fa-solid fa-circle-exclamation
fa-solid fa-circle-half-stroke   fa-solid fa-circle-info
fa-solid fa-circle-xmark         fa-solid fa-download
fa-solid fa-file-lines           fa-solid fa-home
fa-solid fa-lightbulb            fa-solid fa-list
fa-solid fa-magnifying-glass     fa-solid fa-magnifying-glass-minus
fa-solid fa-moon                 fa-solid fa-outdent
fa-solid fa-pencil               fa-solid fa-share
fa-solid fa-sun                  fa-solid fa-triangle-exclamation
fa-solid fa-up-right-from-square fa-solid fa-xmark
fa-brands fa-bitbucket           fa-brands fa-github
fa-brands fa-square-github       fa-brands fa-square-gitlab
fa-brands fa-square-twitter      fa-brands fa-gitlab

(I hope I didn't miss any, but it's still fine as we aren't concerned about the exact number).

size history

This can be traced back to #1955 from September 2024, and as mentioned, it doesn't have anything that we can relate to my recent v7 upgrade, or even who touched the files before me. See the table:

FA version	all.min.js on npm
v6.1.2	~1.7 MiB
v6.5.1	~1.5 MiB
v7.2.0	~1.6 MiB

and a table of the individual style files (I only checked FA v7):

File	Size
solid.min.js	~800 KiB
brands.min.js	~545 KiB
regular.min.js	~115 KiB
fontawesome.min.js	~66 KiB

what can we do?

I don't think we can do much about this without breaking downstream users.

I was thinking that a fix could be to switch to @fortawesome/fontawesome-svg-core and import only the 32 icons we use. The problem is that, via icon_links, we currently allow users to specify any icon of their choice from the FA Free library – and if we were to switch to selective imports to reduce the bundle size (which we could do a lot: from ~1420 KiB to ~160 KiB, almost nine times!), it would break quite a lot of websites and we'll need a migration guide of some sort. So I think letting users declare only the additional icons they need would require a more significant design effort than what the bundle-size savings warrant right now, especially since this is present in 0.17.1 as well. I am unsure how y'all will want to take this forward, but I think there are various other improvements and bugs that would probably be higher-priority.

[drammock]

Based on https://docs.fontawesome.com/web/dig-deeper/svg-core/, it seems fairly easy to:

• switch to svg-core and import only the icons we need for UI elements we provide (and do the dom.watch() trick so that <i> tags still get converted)
• document for end-users how to add extra ones that they want to use --- seems like it's only a few lines of JS, which they could add via html_js_files in their conf.py

This doesn't seem all that bad to me actually; many (?) users may not be using additional icons at all, and everyone would benefit from the reduced webpack size. That said, it is a breaking change for anyone who is using icons other than the ~32 that we choose to build in... If we go for this, it might be worth a quasi-deprecation for one release, where we announce the change and the needed workaround/fix in release X, and actually implement the change in release X+1.

Thoughts?

[agriyakhetarpal]

Yes. If you're willing to do it spread across two release cycles, then this approach will work fine enough! As I was working on this locally for a bit, I still have a branch lingering on with some initial rough work. I can take a look at this if @Yann-P and co. are also on board (or if your sole plan is enough for a go-ahead, and suchlike).

[drammock]

To me it seems worth it, but probably others should weigh in 🤷🏻

I took a look at all the sites listed in our gallery to see what icons they use in icon_links that we aren't using already in our docs. We could avoid pain for those projects at least, if we expand our set of 32 to include these basic and brand ones:

basic:

• box
• box-open
• comments
• download
• envelope
• expand (fullscreen)
• file-lines
• file-video
• gavel
• heart
• house
• magnifying-glass
• pencil
• question
• users

brands:

• blogger
• bluesky
• discord
• discourse
• github (regular and square)
• gitlab
• gitter
• instagram
• linkedin
• mastodon
• python
• stackoverflow
• twitter (regular and square)
• X (regular and square)
• youtube
• zulip (this is new in 7.x, but one site has a zulip link using the "comments" icon, may want official zulip one now)

there were also these custom ones, which we can't do anything about, just noting here for posterity:

• opencollective
• scientific python forum
• binder / mybinder.org
• falcon (web framework)
• Institut für Technische Optik

[agriyakhetarpal]

All good references! I thought about this a bit as well. Maybe there's a programmatic way to find more of the commonly-used ones through some targeted GitHub/Sourcegraph code search queries.

[Yann-P]

I messed around with the code around this issue (mentionned just above)
Still in the "experimenting" phase, I have only tested on pydata-sphinx-theme itself and not very confident about backwards-compat.