MAINT - Defer FontAwesome script to improve Lighthouse performance score #2209

gabalafou · 2025-05-13T13:47:37Z

This pull request:

Adds "defer" attribute to the script tag that loads the FontAwesome library
Consolidates our two custom icon files into one and also loads them with defer
Updates documentation to reflect the above two changes
Excludes images.html from the list of Kitchen Sink pages to check with Lighthouse.

Defer

Warning

When this pull request gets released in the next version of the PyData Sphinx Theme, it will require theme users to update their custom icon entries in html_js_files to include the defer attribute (see the update to the docs page in this pull request).

Without the defer attribute, the entire page has to wait for the FontAwesome script to be downloaded and executed. Lighthouse identified this script as the worst offender. With the defer attribute, the page should be able to load faster.

Excluding images.html

The reason I'm excluding images.html from Lighthouse is because it contains images that are hotlinked from Picsum. I think that this is the reason the Lighthouse performance score comes in too low (below 80). Because when I examined the Lighthouse report for that page, I saw the main reason the page failed was because of a slow Largest Contentful Paint, and when digging into that, the report showed the following table:

Phase	% of LCP	Timing
TTFB	8%	460 ms
Load Delay	89%	5,350 ms
Load Time	2%	110 ms
Render Delay	2%	100 ms

I assume that most of that load delay has to do with hotlinking from Picsum and nothing that we can fix without modifying the Kitchen Sink pages, which we're not supposed to do since those are generated from a script.

Using the Lighthouse score calculator, if I substract 5,000 ms from Largest Contentful Paint, the performance score climbs to 99, which puts it in line with the new performance scores for the other Kitchen Sink pages.

On the flip side, even though this PR excludes images.html from Lighthouse, it actually adds more Kitchen Sink pages to the Lighthouse audit because previously only 5 pages were being checked because the default for maxAutodiscoverUrls is 5.

How I checked this PR

Looked at the results on the lighthouse-audit CI job
Inspected the two custom icons in the preview build
- Brave browser, desktop mode
- Brave browser, mobile mode
- Safari, desktop mode
- Firefox, desktop mode
Checked the preview build to make sure there were no new JavaScript or other errors in the browser dev tools console log.
Checked the updated Header Links docs page in the preview build

gabalafou · 2025-05-13T22:00:21Z

"All checks have passed" 🎉

gabalafou · 2025-05-14T07:24:47Z

Lighthouse performance scores for Kitchen Sink pages after this PR:

Page	Score
admonitions.html	99
api.html	99
blocks.html	99
generic.html	95
images.html	excluded (see note above)
lists.html	99
really-long.html	99
structure.html	99
tables.html	99
typography.html	99

gabalafou · 2025-05-14T07:25:42Z

Consistent success of the link-check CI job depends on #2207

gabalafou

Done self-reviewing

gabalafou · 2025-05-14T07:29:57Z

.github/workflows/lighthouserc.json

+        "/api.html",
+        "/blocks.html",
+        "/generic.html",
+        "/lists.html",


images.html is explicitly excluded because the performance score is likely the result of Picsum taking too long to load images

This a is a good observation, and it is likely this is the root cause.

gabalafou · 2025-05-14T07:30:56Z

docs/_static/pydata-icon.js

Moved into custom-icon.js.

The main reason I did this was that when I tried implementing this with two separate JS files, deferred fontawesome.js, and conf.py like so:

html_js_files = [ ("custom-icon.js", {"defer": "defer"}), ("pydata-icon.js", {"defer": "defer"}), ]

Then for some reason only one of the two custom icons would load correctly on localhost:8000.

I really do not understand why it was working locally before without defer but then failed with defer.

But I also didn't want to spend a long time trying to debug this and digging into the FontAwesome source code. Plus it's better anyway to have fewer network requests for the custom icons (each js file in html_js_files is a separate network request). So I decided to consolidate them into one file and update the docs.

I was never able to figure out why, before this PR, the icon files could be split in two and everything worked, whereas after this PR, splitting the icon files into two results in only the first one working.

That said, I wrapped the consolidated file in various setTimeouts—0, 1, 10, 100, 1000, and 10000 ms—to try to rule out the possibility of a strange race condition.

Well, there probably is some kind of strange race condition, but it probably has to do with subsequent calls to FontAwesome.library.add(). (One clue that this is the case is that if you wrap the code in pydata-icon.js on main in a long enough timeout, say 100 ms, then the icon fails to load.) Based on my testing, so long as add() gets called once with all of the custom icon definitions, instead of for each icon definition, then it seems like everything works fine.

So this PR probably also makes custom icon loading more robust, yay!

gabalafou · 2025-05-14T07:32:11Z

docs/conf.py

@@ -257,7 +257,9 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]
-html_js_files = ["pydata-icon.js", "custom-icon.js"]
+html_js_files = [
+    ("custom-icon.js", {"defer": "defer"}),


See note in PR description. Since this PR changes fontawesome.js to defer, it must also change custom-icon.js (or any code that depends on fontawesome.js to defer)

docs/user_guide/header-links.rst

gabalafou · 2025-05-14T07:55:51Z

docs/_static/custom-icon.js

Moved this to custom-icons to reinforce the idea that all custom icons should be loaded in a single file

gabalafou · 2025-05-14T08:10:37Z

Just noting that in the course of working on this PR I have noticed some of the CI jobs taking a really long time (over 1 hour) and never finishing.

gabalafou · 2025-05-14T08:15:49Z

docs/user_guide/header-links.rst

         ...
      ]

+   .. versionchanged:: v0.17.0


if we don't release this PR with v0.17.0, then we will need to update this to the actual version that incorporates the changes in this PR.

I have added this PR to the v0.17.0 milestone but should I also label it as block-release?

No need to add as block-release, the PR seems pretty much ready now.

This reverts commit 43b4277.

gabalafou · 2025-05-14T09:47:05Z

docs/_static/custom-icons.js

+// This file is referenced in the docs, so if you make changes to it be sure to
+// update the docs too :)


Since this file is not minified on our docs site, I assume it's not minified on theme-adopter sites. So I'm going to remove all unnecessary comments and just link to the docs page instead.

You can see it's not minified by visiting the URL: https://pydata-sphinx-theme.readthedocs.io/en/latest/_static/custom-icon.js?v=74687d30

trallard

Thanks @gabalafou this looks fantastic to me and it is a huge improvement re performance!

I think we are ready to merge so will go ahead with this.

trallard · 2025-05-14T15:40:51Z

.github/workflows/lighthouserc.json

+        "/api.html",
+        "/blocks.html",
+        "/generic.html",
+        "/lists.html",


This a is a good observation, and it is likely this is the root cause.

docs/user_guide/header-links.rst

trallard · 2025-05-14T15:47:55Z

docs/user_guide/header-links.rst

         ...
      ]

+   .. versionchanged:: v0.17.0


No need to add as block-release, the PR seems pretty much ready now.

Defer FontAwesome script to improve Lighthouse performance score

6396ba2

gabalafou added tag: javascript Pull requests that update Javascript code kind: maintenance Improving maintainability and reducing technical debt labels May 13, 2025

gabalafou added 2 commits May 13, 2025 16:45

Ignore images.html (Kitchen Sink)

e371eac

List out URLs for Lighthouse

f6c841f

gabalafou changed the title ~~Defer FontAwesome script to improve Lighthouse performance score~~ MAINT - Defer FontAwesome script to improve Lighthouse performance score May 13, 2025

gabalafou added 2 commits May 13, 2025 20:07

Update docs

4c913f0

remove incorrect line from the docs

1c09339

gabalafou marked this pull request as ready for review May 13, 2025 18:33

oops, duplicated line

0b9a306

gabalafou requested a review from trallard May 14, 2025 07:27

Rename custom-icon.js to custom-icons.js and update docs

815d2ba

gabalafou commented May 14, 2025

View reviewed changes

gabalafou added this to the 0.17.0 milestone May 14, 2025

gabalafou commented May 14, 2025

View reviewed changes

gabalafou added 3 commits May 14, 2025 10:54

use relative link

43b4277

Revert "use relative link"

498abfd

This reverts commit 43b4277.

Accidentally committed wrong code

c501ba3

gabalafou commented May 14, 2025

View reviewed changes

gabalafou added 2 commits May 14, 2025 11:52

remove unnecessary code and comments from custom-icons.js

f68e307

Add note to docs about the importance of only one custom-icons.js

2290b66

trallard previously approved these changes May 14, 2025

View reviewed changes

Update docs/user_guide/header-links.rst

90ccd4a

trallard dismissed their stale review via 90ccd4a May 14, 2025 15:58

trallard approved these changes May 15, 2025

View reviewed changes

trallard merged commit 3e74810 into pydata:main May 15, 2025
30 of 31 checks passed

gabalafou deleted the fix-lighthouse-performance-score branch May 20, 2025 12:32

		// This file is referenced in the docs, so if you make changes to it be sure to
		// update the docs too :)

MAINT - Defer FontAwesome script to improve Lighthouse performance score #2209

MAINT - Defer FontAwesome script to improve Lighthouse performance score #2209

Uh oh!

Conversation

gabalafou commented May 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Defer

Excluding images.html

How I checked this PR

Uh oh!

gabalafou commented May 13, 2025

Uh oh!

gabalafou commented May 14, 2025

Uh oh!

gabalafou commented May 14, 2025

Uh oh!

gabalafou 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!

gabalafou May 14, 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!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gabalafou commented May 14, 2025

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!

trallard left a comment

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!

Uh oh!

Uh oh!

gabalafou commented May 13, 2025 •

edited

Loading

gabalafou May 14, 2025 •

edited

Loading