Skip to content

feat: lazy-load non-critical vendor CSS#965

Open
pivaldi wants to merge 1 commit into
next-theme:masterfrom
pivaldi:feat/lazy-css
Open

feat: lazy-load non-critical vendor CSS#965
pivaldi wants to merge 1 commit into
next-theme:masterfrom
pivaldi:feat/lazy-css

Conversation

@pivaldi

@pivaldi pivaldi commented Jun 27, 2026

Copy link
Copy Markdown
Contributor

Motivation

FontAwesome, Fancybox and KaTeX CSS are render-blocking but not needed for
first paint. Loading them eagerly hurts Lighthouse / Core Web Vitals (FCP, LCP)
on pages that don't use them above the fold. This makes those stylesheets
non-render-blocking via opt-in lazy loading.

Changes

  • New opt-in config (_config.yml), disabled by default so behavior is
    unchanged unless enabled:

    # Performance optimization
    performance:
      # Lazy-load non-critical CSS (FontAwesome, Fancybox, KaTeX)
      # This improves Lighthouse scores by making these CSS files non-render-blocking
      lazy_css: false
  • next_vendors helper (scripts/helpers/engine.js) accepts an options
    object with a lazy flag. When lazy is set and performance.lazy_css
    is enabled, the stylesheet is loaded with the standard preload + onload
    swap technique, plus a <noscript> fallback for JS-disabled clients:

    <link rel="preload" href="" as="style" onload="this.onload=null;this.rel='stylesheet'">
    <noscript><link rel="stylesheet" href=""></noscript>

    JS handling is unchanged (it already uses defer). Existing integrity /
    crossorigin attributes are preserved in both the preload and noscript tags.

  • Templates opt the three non-critical stylesheets in:

    • layout/_partials/head/head.njkfontawesome, fancybox_css
    • layout/_third-party/math/katex.njkkatex

Notes

Testing

  • performance.lazy_css: false (default): tags render exactly as before
    (render-blocking <link rel="stylesheet">).
  • performance.lazy_css: true: FontAwesome / Fancybox / KaTeX CSS emit the
    preload + onload swap with a <noscript> fallback; styles still apply
    with and without JavaScript.

@CLAassistant

CLAassistant commented Jun 27, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@github-actions

Copy link
Copy Markdown

This pull request contains changes to the configuration file. Please make sure the documentation in NexT website is changed or added.
Please edit relevant source files here: https://github.com/next-theme/theme-next-docs/tree/master/source/docs and create a pull request with the changes here: https://github.com/next-theme/theme-next-docs/pulls

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants