The modulepreload Directive

Technical Deep Dive & Specifications

The Transitive Module Waterfall Dilemma

Modern web applications use native JavaScript ES Modules (<script type="module">). While modular code is excellent for developer experience and granular caching, unbundled or partially split ES modules suffer from transitive discovery waterfalls:

[HTML Document] -> <script type="module" src="app.js">
      |
      v (RTT 1: Download & Parse app.js)
  [app.js] -> import { initRouter } from './router.js';
        |
        v (RTT 2: Download & Parse router.js)
    [router.js] -> import { authenticate } from './auth.js';
          |
          v (RTT 3: Download & Parse auth.js)
      [auth.js] -> import { signToken } from './crypto.js';
            |
            v (RTT 4: Download & Parse crypto.js)
        [crypto.js] (Execution finally begins after 4 round-trips!)

====================================================================================================
SERIAL MODULE WATERFALL (Without modulepreload)
====================================================================================================
0ms        100ms       200ms       300ms       400ms       500ms       600ms       700ms
app.js     [==Fetch==][Parse]
router.js             [======Fetch======][Parse]
auth.js                                  [======Fetch======][Parse]
crypto.js                                                   [======Fetch======][Parse]
JS Execution Start: ~720ms ⚠️

modulepreload vs. preload as="script"

Developers often mistakenly use <link rel="preload" href="module.js" as="script">. While this downloads the raw bytes, it leaves the module unparsed and uninstantiated:

+----------------------------------------------------------------------------------------------------+
|                               preload as="script" VS. modulepreload                                |
+----------------------------------------------------------------------------------------------------+
| Characteristic             | `<link rel="preload" as="script">` | `<link rel="modulepreload">`     |
|----------------------------|------------------------------------|----------------------------------|
| **Network Fetch**          | ✅ Downloads raw bytes to cache    | ✅ Downloads raw bytes to cache   |
| **Module Script Context**   | ❌ Generic script context (CORS)   | ✅ Exact ES Module context       |
| **AST Parse & Compile**    | ❌ No (Parses on `<script>` parse) | ✅ YES: Immediate background AST |
| **Module Map Registration**| ❌ No (Stores in HTTP cache only)  | ✅ YES: Pre-registers in Module  |
|                            |                                    |    Map for instant linking       |
| **Dependency Traversal**   | ❌ Fetches target file only        | ⚡ Can speculatively fetch deps  |
| **CORS Mode**              | Defaults to `no-cors`              | Strictly `cors` (per ES spec)    |
+----------------------------------------------------------------------------------------------------+

The WHATWG Module Map Lifecycle

When the browser encounters <link rel="modulepreload" href="...">:

1. Fetch Phase:
   -> Browser issues HTTP GET with Sec-Fetch-Dest: "script" and Mode: "cors".
2. Parse Phase (Background Thread):
   -> JS Engine (V8/JavaScriptCore) compiles raw bytes into an Abstract Syntax Tree (AST).
3. Module Record Creation:
   -> Generates a Source Text Module Record.
4. Module Map Insertion:
   -> Inserts record into document's Module Map keyed by canonical URL.
5. Execution Phase (Main Thread):
   -> When <script type="module"> executes `import './module.js'`, 
      the engine finds the pre-compiled record in the Module Map and executes with 0ms parse delay!

Flattened Parallel Waterfall with modulepreload

====================================================================================================
PARALLEL MODULE GRAPH WITH modulepreload
====================================================================================================
0ms        100ms       200ms       300ms       400ms       500ms       600ms       700ms
app.js     [==Fetch==][Parse]
router.js  [==Fetch==][Parse]
auth.js    [==Fetch==][Parse]
crypto.js  [==Fetch==][Parse]
====================================================================================================
JS Execution Start: ~190ms (74% Faster! 🚀)

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Lines 8–11: Declares <link rel="modulepreload"> for the entire tree of ES modules.
  • When the browser parses the <head>, it fires parallel network fetches for app.js, router.js, auth.js, and crypto-utils.js.
  • As each script finishes downloading, background V8/SpiderMonkey threads parse and compile the AST into the Module Map.
• Line 24: The entry point <script type="module" src="/modules/app.js"> runs. Because all imported child modules are already downloaded, parsed, and instantiated in memory, execution starts synchronously without stalling on network waterfalls.

Expected Browser Render Output (DevTools Network Inspection)

• All 4 module files appear in the Network tab initiated simultaneously at timestamp 0ms.
• Priority column shows High.
• Initiator column shows Link rel=modulepreload for all child chunks.
• When app.js runs import { initRouter } from './router.js', zero network requests are emitted.