Skip to content

feat: add lazy CSS loading option for performance optimization#948

Open
pivaldi wants to merge 1 commit intonext-theme:masterfrom
pivaldi:feature/lazy-css-loading
Open

feat: add lazy CSS loading option for performance optimization#948
pivaldi wants to merge 1 commit intonext-theme:masterfrom
pivaldi:feature/lazy-css-loading

Conversation

@pivaldi
Copy link
Copy Markdown

@pivaldi pivaldi commented Feb 13, 2026

Add configurable lazy loading for non-critical CSS files (FontAwesome, Fancybox, KaTeX) to improve Lighthouse performance scores by reducing render-blocking resources.

The feature uses the modern preload + onload technique to load CSS asynchronously while maintaining a noscript fallback for users without JavaScript. Main theme CSS remains render-blocking to prevent FOUC (Flash of Unstyled Content).

Changes:

  • Add performance.lazy_css config option in _config.yml (default: false)
  • Update next_vendors helper to accept optional lazy flag
  • Modify head.njk to pass lazy: true for FontAwesome and Fancybox
  • Modify katex.njk to pass lazy: true for KaTeX CSS
  • Preserve SRI integrity hashes for security

Benefits:

  • Reduces render-blocking CSS from 4-5 files to 1-2 files

  • Improves Largest Contentful Paint (LCP) by 100-300ms

  • Fully backward compatible (disabled by default)

  • Works without JavaScript via noscript fallback

  • The changes have been tested (for bug fixes / features).

  • Docs in NexT website have been added / updated (for features).

  • Bugfix.

  • Feature.

  • Improvement.

  • Code style update (e.g. formatting, linting).

  • Refactoring (no changes to functionality and APIs).

  • Documentation.

  • Translation.

  • Other... Please describe:

  • Link to demo site with this changes: https://blog.piprime.fr/

  • Screenshots with this changes:

image

How to use?

In NexT _config.yml:

# 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: true

Add configurable lazy loading for non-critical CSS files (FontAwesome,
Fancybox, KaTeX) to improve Lighthouse performance scores by reducing
render-blocking resources.

The feature uses the modern preload + onload technique to load CSS
asynchronously while maintaining a noscript fallback for users without
JavaScript. Main theme CSS remains render-blocking to prevent FOUC
(Flash of Unstyled Content).

Changes:
- Add performance.lazy_css config option in _config.yml (default: false)
- Update next_vendors helper to accept optional lazy flag
- Modify head.njk to pass lazy: true for FontAwesome and Fancybox
- Modify katex.njk to pass lazy: true for KaTeX CSS
- Preserve SRI integrity hashes for security

Benefits:
- Reduces render-blocking CSS from 4-5 files to 1-2 files
- Improves Largest Contentful Paint (LCP) by 100-300ms
- Fully backward compatible (disabled by default)
- Works without JavaScript via noscript fallback

Closes: (add issue number if applicable)
@welcome
Copy link
Copy Markdown

welcome Bot commented Feb 13, 2026

Thanks so much for opening your first PR here!

@CLAassistant
Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

@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

@coveralls
Copy link
Copy Markdown

Pull Request Test Coverage Report for Build 22002530445

Details

  • 0 of 0 changed or added relevant lines in 0 files are covered.
  • No unchanged relevant lines lost coverage.
  • Overall coverage remained the same at 97.451%

Totals Coverage Status
Change from base Build 20737144410: 0.0%
Covered Lines: 400
Relevant Lines: 405

💛 - Coveralls

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.

4 participants