Skip to content

fix: lazy-load DocSearch CSS to reduce inlined stylesheet size#2494

Closed
aeneasr wants to merge 4 commits intomasterfrom
split-css
Closed

fix: lazy-load DocSearch CSS to reduce inlined stylesheet size#2494
aeneasr wants to merge 4 commits intomasterfrom
split-css

Conversation

@aeneasr
Copy link
Copy Markdown
Member

@aeneasr aeneasr commented Mar 27, 2026

Summary

  • Extracts ~30KB of DocSearch CSS from the main inlined stylesheet into a separate docsearch.<hash>.css file
  • Lazy-loads the DocSearch stylesheet only when the user first interacts with the search button (mouseover/focus/click)
  • Reduces inlined CSS per page from ~132KB to ~102KB (~23% reduction)

How it works

The preload-css.js post-build plugin now:

  1. Splits the compiled CSS into blocks using a brace-depth parser that handles nested @media rules
  2. Detects DocSearch blocks (.DocSearch selectors / --docsearch- variables), keeping mixed :root blocks in main CSS
  3. Writes the DocSearch CSS to a separate hashed file
  4. Injects a small inline script that attaches mouseover/focus/click listeners to the search button and loads the stylesheet on first interaction

Test Plan

  • Run npm run build and verify no errors
  • Check that inlined <style> in HTML contains no .DocSearch classes
  • Verify docsearch.<hash>.css is present in build/assets/css/
  • Open built site, open DevTools Network tab — confirm DocSearch CSS loads only after hovering/clicking the search button
  • Confirm search works correctly after interaction

aeneasr and others added 2 commits March 26, 2026 18:17
Extracts ~30KB of DocSearch CSS from the main stylesheet into a
separate file (docsearch.<hash>.css) that is only loaded when the
user first interacts with the search button (mouseover/focus/click).
Reduces inlined CSS from ~132KB to ~102KB.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@aeneasr aeneasr changed the title perf: lazy-load DocSearch CSS to reduce inlined stylesheet size fix: lazy-load DocSearch CSS to reduce inlined stylesheet size Mar 27, 2026
aeneasr and others added 2 commits March 27, 2026 16:39
The button is always visible on initial load, so its styles must be
inlined rather than lazy-loaded.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
--docsearch-* custom properties (e.g. --docsearch-searchbox-height) are
referenced by .DocSearch-Button styles. Deferring them caused the button
to snap to the correct size when the lazy CSS loaded, triggering a
layout shift. Now all :root variable definitions stay in the inlined CSS.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@aeneasr
Copy link
Copy Markdown
Member Author

aeneasr commented Mar 27, 2026

Unfortunately, these hacks dont work.

Right now, the question is if it makes sense to even keep the search bar since I heard it doesnt work well, if it just adds bloat to the website and makes it slow.

Or we fix the search and it becomes really good, which is also an option ;)

But the work here isn't mathing, it just creates some ugly visual flakes.

@aeneasr aeneasr closed this Mar 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants