For an ES module entry point, what does <link rel="modulepreload" href="/app.js"> do that <link rel="preload" as="script" href="/app.js"> does not?

## The waterfall problem modulepreload exists to solve An ES module graph is discovered by *reading*. The browser fetches `/app.js`, parses it, sees `import { x } from './a.js'`, fetches `a.js`, parses it, sees its imports, and so on. Each level of the graph is one more round trip that could not have started earlier, because the browser did not know the URL existed. On a deep dependency tree over a high-latency connection, that serialisation dominates the load, and it is invisible in a bundle report because the bytes are small — it is the *shape* that costs. `<link rel="modulepreload">` exists to flatten that waterfall. ## What each hint actually stores `<link rel="preload" as="script" href="/app.js">` performs a fetch and parks the raw response. The browser does not interpret it. When a `<script type="module" src="/app.js">` later asks for it, the bytes come from cache — a real saving, but only for that one file. The imports inside it are still discovered by parsing after the fact, one level at a time. `<link rel="modulepreload" href="/app.js">` is defined in terms of the module system: ```html <script type="module" src="/app.js"></script> <link rel="modulepreload" href="/lib/router.js"> <link rel="modulepreload" href="/lib/store.js"> ``` It fetches the resource, parses it as a module, and inserts it into the **module map** — the per-document registry keyed by URL that guarantees each module is fetched and evaluated at most once. By the time the entry script runs, those modules are already resolved rather than merely cached. The specification also permits the browser to fetch the module's **static import dependencies**, and browsers do, so a single hint on a well-chosen entry point can start the whole subtree at once. ## Fetch mode comes out right Module scripts are always fetched in CORS mode. `modulepreload` inherits that, so a same-origin hint matches the real request with no extra attributes; a cross-origin module needs `crossorigin` on the hint just as it does on the script. With `preload as="script"` you have to reproduce that by hand, and forgetting is the classic bug: the plain preload requests the file in a mode the module request cannot reuse, so the browser fetches it twice and logs a warning that the preload went unused. This is the same request-matching rule that governs every preload, but here the correct answer is usually "use the module-aware hint instead". ## What it still does not do Evaluation. `modulepreload` prepares a module; it does not run it. Top-level code executes when something actually imports the module or when the entry `<script type="module">` evaluates. The hint is also useless without a consumer — a modulepreload for a module nothing imports is wasted bandwidth, exactly like any other unused hint. It also only helps with **statically analysable** imports. A dynamic `import()` whose specifier is built at runtime cannot be discovered by anybody in advance; if such a chunk is on the critical path, it needs its own explicit hint. That is the usual reason a hand-written `modulepreload` appears next to build-generated ones. ## Where these hints come from in practice You rarely hand-write them for a real application. Module URLs are hashed and change per build, so the hints have to be generated from the build manifest alongside the entry script — the same tooling that emits the `<script type="module">` tag emits the `modulepreload` lines for the chunks that entry needs. Hand-maintained hints go stale on the first rename and become invisible waste. ## Deciding how many to emit The usual failure is a template that emits a `modulepreload` for every chunk in the build. Now the browser starts dozens of high-priority requests, all sharing the connection with the CSS and the LCP image, including chunks for routes this page will never load. The right scope is the modules the **current** entry point needs to become interactive — the graph that would otherwise be discovered level by level — and nothing beyond it. As with every hint in this family, the value is in moving discovery earlier for things you were going to fetch anyway; the moment it starts fetching things you were not, it is a regression.