Optimizing critical resources
The runtime engine plays a crucial role in the initial display of a page.
Preload runtime engine
Without preload hints, the CDN runtime script and its default manifest can be discovered too late. Runtime rendering may experience delays in downloading and initializing until the first contentful paint if runtime-critical resources are discovered late.
Conceptual request waterfall for the CDN runtime script and default manifest. The marker shows when the page can first paint after critical runtime resources are ready; positions are illustrative, not measured network data.
Without preload
The runtime script starts late, then imports the manifest.
With preload
The runtime script and manifest module start early, so first paint can move earlier.
Preload the CDN runtime with as="script". The CDN runtime imports its split default manifest as a JSON module before starting; preload that JSON module with modulepreload, as="json", and crossorigin so the runtime can reuse the module.
Use <link rel="preload"> and <link rel="modulepreload"> to preload the critical resources.
<!DOCTYPE html><html lang="en" hidden><head> <link rel="preload" as="style" href="https://cdn.master.co/css@rc/base.css"> <link rel="preload" as="script" href="https://cdn.master.co/css-runtime@rc"> <link rel="modulepreload" as="json" crossorigin href="https://cdn.master.co/css-runtime@rc/default-manifest.json"> <link rel="stylesheet" href="https://cdn.master.co/css@rc/base.css"> <script src="https://cdn.master.co/css-runtime@rc"></script></head></html>With these preload hints in place, the runtime script and default manifest requests start during document parsing and download in parallel with the stylesheet. The parser and runtime later reuse the preloaded script and JSON module instead of waiting on new requests.
You are telling the browser that you would like to fetch it sooner than the browser would otherwise discover it.
Preload runtime project manifests
Official runtime integrations can split the project manifest into a hashed JSON asset in production. The runtime must load that manifest before it can interpret project tokens, modes, components, utilities, and variants from your CSS entry graph.
Let runtime-only integrations preload the project manifest JSON.
<!DOCTYPE html><html lang="en" hidden><head> <link rel="modulepreload" as="json" crossorigin href="/assets/master-css-manifest.<hash>.json"> <script type="module" src="/assets/main.<hash>.js"></script></head></html>The modulepreload starts the JSON module request while the browser is still parsing the document. The runtime module later imports virtual:master-css-manifest, whose facade imports the same JSON module. Matching as="json" and crossorigin lets the browser reuse the preloaded module instead of issuing a second request.
This optimization applies to pure runtime rendering. Progressive rendering already has critical CSS in style#master-css, so its page hydration manifest should not be preloaded.
Choose the right manifest JSON
Master CSS uses different JSON files for different handoff points:
| JSON file | Used by | Preload? |
|---|---|---|
| CDN default manifest | CDN runtime-only pages that use the packaged default preset manifest. | Yes, when using the CDN runtime. |
| Project manifest asset | Official runtime integrations that emit master-css-manifest.<hash>.json for virtual:master-css-manifest. | Yes, in pure runtime mode when the integration injects the runtime. |
| Page hydration manifest | Progressive and pre-rendered pages that already contain style#master-css. | No. The browser can paint without it. |
Defer runtime engine
Defer the runtime engine, because the critical CSS has already been pre-rendered on the page.
<!DOCTYPE html><html lang="en"><head> <script type="module" src="/main.js"></script></head></html>Do not preload the runtime engine in progressive rendering mode.
<!DOCTYPE html><html lang="en"><head> <link rel="modulepreload" href="/main.js"> </head></html>Do not preload page hydration manifests
Progressive rendering can externalize the page hydration manifest:
<style id="master-css" data-master-css-hydration-manifest="/_master-css/hydration/master-css-hydration.<hash>.json">...</style>Do not add a preload hint for this JSON file.
The page hydration manifest is runtime handoff data. It lets the runtime adopt the rules that already exist in style#master-css, but it is not required for the browser to paint the first screen. Let the runtime import it when hydration starts. If that import fails or the data is invalid, the runtime rebuilds from connected DOM classes.
This is different from runtime project manifests. A runtime-only page needs its project manifest before it can interpret classes. A progressive page already has the first-response rules in style#master-css, so its page hydration manifest only describes CSS that was already rendered into that one HTML response.
Benefits
Preloading critical assets can improve the following metrics:
- First Contentful Paint (FCP): Preloading critical assets helps accelerate the loading of essential scripts, such as JavaScript, resulting in faster FCP. This means that the main content of the webpage can be displayed more quickly in the user's browser, enhancing their perception and experience.
- First Meaningful Paint (FMP): By preloading critical scripts, the browser can start parsing and rendering the script earlier, leading to faster FMP. This allows users to see meaningful content more rapidly, improving the visual presentation of the page.
- Time to Interactive (TTI): Preloading critical scripts reduces waiting time for users, resulting in a faster Time to Interactive. When the critical script has been downloaded and is ready, users can interact with the webpage more quickly, providing a better user experience.
Preloading critical scripts enhances the download and execution speed of the scripts, thereby improving metrics such as First Contentful Paint, First Meaningful Paint, and Time to Interactive.