Performance: Asset Loading Strategy
Relevant source files
The following files were used as context for generating this wiki page:
- themes/matrix-flow/source/js/code-splitter.js
- themes/matrix-flow/source/js/module-loader.js
- themes/matrix-flow/source/js/resource-preloader.js
- themes/matrix-flow/scripts/critical-css-extractor.js
- themes/matrix-flow/scripts/critical-css.js
- themes/matrix-flow/_css-config.yml
- themes/matrix-flow/source/js/performance-monitor.js
- themes/matrix-flow/CSS-INTEGRATION-README.md
The asset loading strategy for the Matrix Flow theme is a multi-faceted system designed to optimize front-end performance, focusing on fast initial rendering and efficient, on-demand loading of resources. The primary goals are to improve Core Web Vitals, reduce the number of initial HTTP requests, and prevent Flash of Unstyled Content (FOUC) by prioritizing critical assets.
This strategy is implemented through a combination of build-time scripts for CSS optimization and client-side JavaScript modules for intelligent resource loading. Key components include a critical CSS pipeline, a priority-based JavaScript module loader, and an advanced resource preloader that adapts to network conditions. The system ensures that only necessary assets are loaded for the initial viewport, while deferring non-essential CSS and JavaScript until they are needed or the browser is idle.
Core Components
The client-side loading strategy is managed by three main classes: CodeSplitter, ModuleLoader, and ResourcePreloader. They work together to manage the lifecycle of JavaScript modules and other resources.
This diagram shows the main classes involved in the asset loading strategy and their conceptual relationships.
Sources: themes/matrix-flow/source/js/code-splitter.js, themes/matrix-flow/source/js/module-loader.js, themes/matrix-flow/source/js/resource-preloader.js
CSS Loading Strategy
The CSS loading strategy is designed to deliver the fastest possible First Contentful Paint (FCP) by inlining critical styles and deferring the rest.
Sources: themes/matrix-flow/scripts/critical-css-extractor.js, themes/matrix-flow/scripts/critical-css.js, themes/matrix-flow/_css-config.yml
Critical CSS Extraction
At build time, a script (critical-css-extractor.js) analyzes the main stylesheet (style.css) to separate critical and non-critical CSS rules. Critical CSS includes styles required for rendering the "above-the-fold" content.
The following selectors and rules are identified as critical:
- Base elements:
html,body,*,:root - Core layout:
.fullscreen-container,.responsive-grid,.site-header,.site-main - Key visual elements:
.logo-glitch,.main-nav,#matrix-canvas - Essential typography:
h1,h2,h3,p,a - Critical animations and media queries for responsiveness.
Sources: themes/matrix-flow/scripts/critical-css-extractor.js:23-47, themes/matrix-flow/scripts/critical-css.js:15-44
CSS Delivery Flow
The extracted CSS is delivered to the browser in two stages to optimize rendering.
This diagram illustrates the build-time extraction and browser rendering flow for CSS.
Sources: themes/matrix-flow/scripts/critical-css-extractor.js, themes/matrix-flow/CSS-INTEGRATION-README.md
-
Inline Critical CSS: The extracted critical CSS is minified and embedded directly into the HTML head within a
<style>tag. This is controlled by theinline_critical: truesetting in_css-config.ymland prevents FOUC by ensuring layout styles are available before the page starts rendering.
Sources: themes/matrix-flow/scripts/critical-css-extractor.js:123-135, themes/matrix-flow/_css-config.yml:9 -
Asynchronous Non-Critical CSS: The remaining (non-critical) styles are loaded asynchronously using a
<link rel="preload">tag with anonloadhandler. This downloads the stylesheet without blocking rendering and applies it once loaded. A<noscript>fallback is included.
Sources: themes/matrix-flow/scripts/critical-css-extractor.js:143-146, themes/matrix-flow/scripts/critical-css.js:101-104
JavaScript Module Loading
JavaScript is managed by the CodeSplitter and ModuleLoader classes, which implement a sophisticated, priority-based dynamic loading system.
Module Registration and Prioritization
Modules are registered in CodeSplitter with metadata that dictates how and when they should be loaded. This includes priority, dependencies, and size for performance budgeting.
| Module Name | Priority | Path | Dependencies | Load Trigger |
|---|---|---|---|---|
viewport-manager | critical | /js/viewport-manager.js | [] | Immediate |
matrix-animation | critical | /js/matrix.js | [] | Immediate |
newsletter | high | /js/newsletter.js | [] | interaction |
lazy-loader | medium | /js/lazy-loader.js | [] | scroll |
performance-analytics | low | /js/performance-analytics.js | performance-monitor | idle |
Sources: themes/matrix-flow/source/js/code-splitter.js:35-83
Module Loading Triggers
Modules are loaded based on different triggers to optimize resource usage:
| Trigger | Mechanism | Description |
|---|---|---|
| Critical | loadCriticalModules() on initialization. | Loads modules essential for the initial page view immediately. |
| Viewport-based | IntersectionObserver on [data-modules] elements. | Loads modules only when the corresponding component scrolls into the viewport. |
| Interaction-based | Event listeners for mousedown, touchstart, keydown. | Preloads modules like newsletter.js on the first user interaction, assuming they will be needed soon. |
| Idle Time | requestIdleCallback (with setTimeout fallback). | Loads low-priority modules like analytics when the browser is idle to avoid impacting user experience. |
Sources: themes/matrix-flow/source/js/code-splitter.js:85-95, 230-256, 259-277, 280-297, themes/matrix-flow/source/js/module-loader.js:33-58, 60-78
Module Loading Sequence
The loadModule function in CodeSplitter orchestrates the loading process, handling dependencies, caching, and retries.
This diagram shows the sequence of events when a module is requested via loadModule.
Sources: themes/matrix-flow/source/js/code-splitter.js:109-150
Resource Hinting and Preloading
The ResourcePreloader class enhances performance by providing the browser with hints about which resources will be needed, allowing it to optimize fetching.
Sources: themes/matrix-flow/source/js/resource-preloader.js
Resource Hint Types
dns-prefetch: Initiates an early DNS lookup for external domains (e.g.,fonts.googleapis.com) to reduce latency when the resource is requested.
Sources: themes/matrix-flow/source/js/resource-preloader.js:39-49preconnect: Goes a step further thandns-prefetchby also performing the TCP handshake and TLS negotiation. This is used for critical external origins.
Sources: themes/matrix-flow/source/js/resource-preloader.js:51-66preload: Tells the browser to fetch a resource for the current navigation with high priority. It's used for critical assets like the main CSS file, fonts, and critical JavaScript modules.
Sources: themes/matrix-flow/source/js/resource-preloader.js:68-97prefetch: A low-priority hint for resources that might be needed for future navigations. This is used for assets likelazy-loader.js.
Sources: themes/matrix-flow/source/js/resource-preloader.js:99-118
Adaptive Preloading
The ResourcePreloader implements an adaptive strategy that adjusts its behavior based on the user's network connection, detected via navigator.connection.
- Conservative (
slow-2g,2g,saveData: true): Only critical resources are preloaded. Non-critical preloads are cleared to save bandwidth. - Moderate (
3g): Preloads critical and high-priority resources. - Aggressive (
4gor faster): Preloads all queued resources.
Sources: themes/matrix-flow/source/js/resource-preloader.js:195-233
Performance Monitoring
The system includes a PerformanceMonitor class and integrates with the PerformanceObserver API to track the effectiveness of the loading strategy.
- Module Performance: The
CodeSplitteruses aPerformanceObserverto listen forresourceentries. It logs the load time and transfer size of each JavaScript module, providing feedback on the loading performance.
Sources: themes/matrix-flow/source/js/code-splitter.js:85-107 - Core Web Vitals: The
PerformanceMonitorclass is designed to collect key metrics like Navigation Timing, Resource Timing, FCP, LCP, and CLS to generate a comprehensive performance report.
Sources: themes/matrix-flow/source/js/performance-monitor.js:33-112, 140-180
Summary
The asset loading strategy is a comprehensive system that prioritizes a fast initial user experience. It achieves this by inlining critical CSS, deferring non-essential assets, and intelligently preloading resources based on priority, user interaction, and network conditions. By splitting code and using modern browser APIs like IntersectionObserver and requestIdleCallback, the theme minimizes render-blocking resources and ensures that assets are loaded efficiently and only when needed. This proactive and adaptive approach is fundamental to the theme's performance-first architecture.