Skip to content

perf: fix render-blocking CSS and font display #930

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
moshams272 wants to merge 1 commit into from
+33 −6
Closed

perf: fix render-blocking CSS and font display #930

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 25 additions & 3 deletions src/generators/legacy-html/template.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,32 @@
<meta name="nodejs.org:node-version" content="__VERSION__" />
<title>__SECTION__ | Node.js __VERSION__ Documentation</title>
<link
rel="stylesheet"
href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback"
rel="preload"
href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=swap"
as="style"
onload="
this.onload = null;
this.rel = 'stylesheet';
"
Comment on lines +13 to +16

@bjohansebas bjohansebas Jul 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we should preload the Google Fonts stylesheet obviously without any JavaScript, just using the standard preload/prefetch approach. I'm still surprised we're using Google Fonts instead of hosting them ourselves, but that's a separate discussion.

@moshams272 moshams272 Jul 22, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Self-hosting the fonts would be the ideal solution 👀

/>
<link rel="stylesheet" href="assets/style.css" />
<noscript>
<link
rel="stylesheet"
href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=swap"
/>
</noscript>
<link
rel="preload"
href="assets/style.css"
as="style"
onload="
this.onload = null;
this.rel = 'stylesheet';
"
/>
<noscript>
<link rel="stylesheet" href="assets/style.css" />
</noscript>
Comment on lines +24 to +35

@avivkeller avivkeller Jul 21, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO we shouldn't mix CSS and JavaScript in this way. CSS shouldn't rely on the JavaScript capabilities of a given machine.

Unfortunately, I think we need to just eat the perf issue. We might be able to reduce the size of CSS in doc-kit, perhaps, but I won't make you work on that, it's our fault, and not something that's particularly 'fun' or easy to fix.

@moshams272 moshams272 Jul 22, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can use library critters, It extracts the Critical CSS and inlines it directly into a <style> tag in the generated HTML. This means the initial render relies on zero client-side JS and has no render-blocking network requests, WDUT?!

@moshams272 moshams272 Jul 22, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I searched on it since few hours, #930 (comment)

<link rel="canonical" href="https://nodejs.org/api/__FILENAME__.html" />
<script async defer src="assets/api.js" type="text/javascript"></script>
<script>
Expand Down
11 changes: 8 additions & 3 deletions src/generators/web/template.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,21 @@
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>${title}</title>
<link rel="stylesheet" href="${root}styles.css" />
<link rel="preload" href="${root}styles.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
<noscript>
<link rel="stylesheet" href="${root}styles.css">
</noscript>

@cursor cursor Bot Jul 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Async critical CSS causes FOUC

Medium Severity

The main stylesheets (styles.css / assets/style.css) are loaded with the non-blocking rel="preload" pattern, but no critical CSS is inlined. That pattern is meant for non-critical CSS; applying it to the sole layout stylesheet lets the page paint unstyled, then snap into place when CSS arrives. This undoes the existing theme FOUC guards and can also shift layout-dependent behavior such as sidebar scrolling.

Additional Locations (1)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 09ba17a. Configure here.

@moshams272 moshams272 Jul 21, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can use library critters, WDUT?!

<meta property="og:title" content="${title}">
<meta property="og:type" content="website">

${head}

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link rel="stylesheet"
href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono&family=Open+Sans:ital,wght@0,300..800;1,300..800" />
<link rel="preload" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono&family=Open+Sans:ital,wght@0,300..800;1,300..800&display=swap" as="style" onload="this.onload=null;this.rel='stylesheet'">
<noscript>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono&family=Open+Sans:ital,wght@0,300..800;1,300..800&display=swap" />
</noscript>

<!-- Apply theme before paint to avoid Flash of Unstyled Content -->
<script>${themeScript}</script>
Expand Down
Loading