Defer non-critical JS for slightly faster page load under CPU+Network simultaneous bottleneck

[evnchn]

Motivation

Still in the mood of speed improvement.

So I was reading https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script again...

Basically, loading behaviour wise, there's 3 valid options:

1. Normal script
2. Defer script
3. Async script

(Don't think about defer async. It has been mentioned that if async is set, "If the attribute is specified with the defer attribute, the element will act as if only the async attribute is specified", meaning async + defer => async).

I then took a look at the script situation in NiceGUI:

1. No script in head
2. Body's empty, no elements
3. Main script is a <script type="module">, which is "defer by default"

Then I thought: Can I have the rest of the NiceGUI's scripts be defer as well, since they need to run before the main script only, and not any earlier. We don't need to block up the parser while those scripts load?

And yes, indeed, there is performance uplift.

Implementation

• Change the scripts from normal scripts to defer scripts.
  • Left the ES module shim in-tact since that probably has to load ASAP.
  • Left Socket.IO in-tact because we'd have to move it anyways if we adapt Move Socket.IO initialization all the way to head + Pre-Mount Message Queueing #4756
  • Both instances, maybe defer would make it even faster, or it would break things. I'll see when I have time.

Progress

• I chose a meaningful title that completes the sentence: "If applied, this PR will..."
• The implementation is complete.
• Pytests have been added (or are not necessary).
• Documentation has been added (or is not necessary).

-> No need pytest and documentation. As long as existing tests don't break, Id be happy

Results showcase

Using Fast 4G profile, 4x CPU slowdown.

Before:

After:

Finish: 6.47s -> 5.99s
DOMContentLoaded: 4.69s -> 4.38s
Load: 5.69s -> 5.18s

About save 5s.

Reference: 4G network latency 165ms. I am not saying that we are saving 3x the network latency, but it just puts things into perspective.

Worthy of note:

• No performance uplift if network is not slowed down and only CPU slowdown, since the network request would complete in an instant, and we didn't really block the parser for much.
• No performance uplift if CPU is not slowed down and only network slowdown, since the parsing would complete in an instant, and we can't block the parser if completes in a blink of the eye.
• Only notice performance uplift if you apply BOTH network slowdown and CPU slowdown.

May want to test with more slowdown and Slow 4G later. 3G's too much.

[evnchn]

Found where the speed improvement was, after staring at the waterfall.

[falkoschindler]

Interesting! I mean, under good conditions you won't notice a difference. But there doesn't seem to be any risk in adding defer, right? Or could it break anything (or cause worse load times somehow)?

ChatGPT's risk assessment sounds promissing:

What the PR actually does

The patch just adds the boolean defer attribute to every classic <script src="…"> tag that NiceGUI injects into templates/index.html (7 adds, 7 dels).
Nothing else changes.

How browsers handle defer (classic scripts)

Phase	Without defer	With defer
HTML parsing	stops until the script file has been fetched & executed	keeps going while the file is fetched
Script execution	immediately, at the point the tag is met	after parsing finishes, but before DOMContentLoaded
Execution order	top-to-bottom, because the parser blocks	still top-to-bottom (the spec keeps order for all deferred scripts)

Performance impact

• First HTML parse becomes non-blocking → a small win, especially on mobile networks with high RTT.

• No extra network requests are added; the files were already being downloaded in parallel thanks to HTTP/2.

• Runtime cost is unchanged; execution merely shifts a few milliseconds later.

Real-world micro-benchmarks in the PR description show slightly faster Time to First Byte + First Contentful Paint under a throttled “slow-3G/low-CPU” profile; there was no measurable regression.

Recommendation

Unless you have:

• a script that must run synchronously while the parser is blocked, or

• a requirement to support browsers older than IE 11,

there is no functional risk in merging this PR.
Worst case, any inline script with defer is simply ignored; best case, initial rendering is marginally faster on constrained devices.

If you want to be extra-safe you can:

1. Deploy the patch to a staging server and check for any flash-of-unstyled-content on a throttled 3G profile.

2. Run the existing end-to-end test suite in “slow-network” mode; failures would highlight hidden timing dependencies.

Otherwise, the change is straightforward and should only provide a small performance upside.

Ready to merge? Or are you still testing?

[evnchn]

@falkoschindler I believe this is ready to merge.

My brain was just stuck in the thinking mode of #4756 for no reason 😅 and thinking that I need to init the Socket.IO ASAP.

But, before that PR gets merged, Socket.IO isn't initiated until we run createApp down in the main module script, so we can also defer Socket.IO.

It has a very very tiny risk of breaking existing code, if the user uses add_body_html to make their own Vue app like this:

ui.add_body_html('''
    <script>
    console.log(Vue); // breaks after this PR
    </script>
    ''')

But I don't think we should be held back by that very niche use case.

[evnchn]

Before I forget: If you really need to use Vue in add_body_html (which spoiler, by all means you should not, just embrace NiceGUI fully...), just put it after DOMContentLoaded.

document.addEventListener('DOMContentLoaded', function() {
    // Your code here
});