modulepreload Explained: Preloading JavaScript Modules
rel=modulepreload tells the browser to fetch and prepare an ES module early, flattening import waterfalls. How it differs from preload and when to use it.
<link rel="modulepreload"> is a resource hint that tells the browser to fetch an ES module ahead of time, using the same request settings a real import would use, and to store it in the document’s module map so it is ready the moment code imports it. Its main job is to flatten import waterfalls — the chain of sequential network requests that happens when one module imports another, which imports another, and the browser only discovers each step after the previous file arrives.
The waterfall problem
Native ES modules are discovered lazily. When the browser loads an entry point with <script type="module" src="/app.js">, it has to download and parse app.js before it can see what app.js imports.
// app.js
import { router } from "./router.js";
// router.js
import { fetchUser } from "./api.js";
// api.js
import { formatDate } from "./utils/date.js";
That is four round trips in sequence: app.js, then router.js, then api.js, then date.js. Each request waits on the one before it. On a fast connection the delay is small; on a high-latency mobile network, every extra hop adds noticeable time before your app runs.
Bundlers exist partly to avoid this by concatenating modules. But modern builds still emit multiple chunks for code splitting, and those chunks import each other natively. The waterfall comes back at the chunk level.
What modulepreload does
You list the modules you know the page will need:
<link rel="modulepreload" href="/router.js">
<link rel="modulepreload" href="/api.js">
<link rel="modulepreload" href="/utils/date.js">
<script type="module" src="/app.js"></script>
Now the browser can request all four files in parallel as soon as it parses the HTML. When app.js finally runs its import statements, the dependencies are already in the module map, so there is no further network wait.
Beyond fetching, browsers may also parse and compile a preloaded module ahead of time, moving that work off the critical path. The module is not executed until something imports it, so preloading never changes the order in which your code runs.
Why not just use rel=preload?
The generic <link rel="preload" as="script"> hint predates modules, and it is the wrong tool here. The difference is in how the request is made.
rel=preload as=script | rel=modulepreload | |
|---|---|---|
| Request mode | Classic script settings | Module settings (CORS, same as import) |
| Stored in | HTTP cache / preload cache | Document module map |
Reused by import | Not reliably; may refetch | Yes |
| May parse/compile early | No | Yes, at browser discretion |
| Dependencies | Not considered | Browser may fetch them; do not rely on it |
Module scripts are always fetched in CORS mode with specific credentials settings. A classic preload is fetched with different settings, so when the module loader goes looking for the file it may not match the preloaded response, and the browser downloads it a second time. You pay for two requests and get no benefit. modulepreload uses the module request settings by default, so the match is guaranteed.
If your modules come from another origin and need credentials, add the crossorigin attribute to the modulepreload link with the same value your script tag uses, just as you would for any cross-origin module.
Dependencies are not guaranteed
A detail that trips people up: the specification allows a browser to also fetch a preloaded module’s own imports, but does not require it. Some browsers fetch only the exact file you listed.
The safe pattern is to list every module in the chain explicitly, not just the top one. If you hint only router.js, a browser that skips dependencies will still discover api.js and date.js one at a time. Listing all of them turns a serial chain into a single parallel batch everywhere.
How build tools use it
You rarely need to write these tags by hand in a bundled app. Tools like Vite analyze the module graph at build time and inject modulepreload links for the chunks an entry point depends on. They also handle dynamic imports: when code calls import("./settings.js"), the generated code can preload that chunk’s dependencies at the same moment, so the lazy route loads in one parallel step instead of a cascade.
This pairs naturally with tree shaking, which reduces what each chunk contains, and with import maps, which let unbundled apps use bare specifiers. With import maps, you can still preload the resolved URLs directly; the module map is keyed by the final URL, not by the specifier you wrote in your code.
When to use it
Use it for modules on the critical path. The entry point’s static dependencies, the code for the first route, and shared framework chunks are all good candidates. They are needed on every load, and hinting them shortens the time to interactive.
Use it just before a likely dynamic import. If a user hovers over a button that opens a heavy editor, inserting a modulepreload link for the editor’s chunk on hover gives it a head start without loading it for everyone.
Do not preload everything. Every hint competes for bandwidth with the HTML, CSS, and images. Preloading modules a page may never use slows down what it does use. Treat it like any other entry in your resource hints budget: few, critical, and measured.
Watch for modules with top-level work. Preloading does not execute code, but once imported, modules that use top-level await can still block their importers. Preloading speeds up the fetch, not the awaited work inside.
Checking that it works
In the network panel of your browser’s developer tools, preloaded modules should start downloading right after the HTML is parsed, in parallel, rather than staggered behind one another. The initiator column will point to the <link> element. If you see the same module URL requested twice, a mismatched hint — usually rel=preload on a module or a missing crossorigin — is the likely cause.
It is also worth understanding the broader module system you are working with; our comparison of ESM vs CommonJS covers why native modules load the way they do.
The takeaway
rel=modulepreload is the module-aware version of preload. It fetches an ES module with the correct request settings, may compile it early, and places it where import will find it, turning sequential import chains into parallel downloads. Use it instead of rel=preload as=script for modules, list every critical module explicitly rather than trusting the browser to follow dependencies, and let your build tool generate the tags wherever it can.
Tagged
Keep reading
Takina · · 5 min read Passive Event Listeners: Smoother Scrolling in JavaScript
Passive event listeners tell the browser a handler won't call preventDefault(), so scrolling starts at once. How { passive: true } works and when to use it.
Takina · · 5 min read Code Splitting Explained: Smaller JavaScript Bundles
Code splitting breaks one large JavaScript bundle into smaller chunks loaded on demand. How bundlers do it, the main strategies, and the trade-offs.
Takina · · 4 min read What Is requestAnimationFrame? Smooth JS Animation
requestAnimationFrame schedules a callback right before the browser repaints, syncing JavaScript animation to the display's refresh rate. How it works.