React Reference ยท react-dom Resource and Form APIs
React preloadModule() function
Reference for react-dom preloadModule(): download an ES module and its dependencies before an import runs, using modulepreload, with options and pitfalls.
preloadModule(href, options) starts downloading an ES module so that a later import of it finishes quickly. The browser fetches the file, parses it and also fetches the modules it imports, but it does not run it. React renders the call as <link rel="modulepreload"> in the document head and deduplicates repeated calls.
Use it for code you know is coming: the chunk behind the next route, a heavy editor loaded on a button press, or a Web Worker script. For a module that should also execute immediately, use preinitModule. For classic scripts and every other file type, use preload.
import { preloadModule } from 'react-dom'; preloadModule('/assets/editor.js', { as: 'script' });
Try it
The ordinary module shows (default) because React leaves the as attribute out for scripts; only the worker carries it.
Hover or tab to the link repeatedly: the call count grows, the link count stays at 1.
Syntax
preloadModule(href) preloadModule(href, options)
function preloadModule( href: string, options?: { as?: 'script' | 'worker' | 'sharedworker' | 'serviceworker' | 'audioworklet' | 'paintworklet'; crossOrigin?: 'anonymous' | 'use-credentials' | ''; integrity?: string; nonce?: string; } ): void;
| Name | Description |
|---|---|
href |
URL of the module. Must be a non-empty string. |
options.as |
Kind of consumer when it is not an ordinary module script, such as 'worker'. Omit it for normal import. |
options.crossOrigin |
CORS mode used by the later import. Modules are fetched with CORS, so a cross-origin module needs a server that sends the right headers. |
options.integrity |
Subresource Integrity hash. |
options.nonce |
Content Security Policy nonce. |
Returns: nothing (undefined).
Errors / edge cases: an empty href, or an as value that is not valid for modulepreload, logs a development error and adds nothing.
Usage notes
- Downloads and parses, but never runs. Top-level code of the module does not execute until something imports it. That makes the hint safe for modules with side effects.
- Dependencies are included. Unlike
preload,modulepreloadalso fetches the static imports of the module, which is why it suits bundler chunks. - Dedupe with
preinitModule. If the same URL was already passed topreinitModule, a laterpreloadModuleadds nothing, because the module is already requested. - Use final URLs. In bundled apps, file names carry content hashes. Take the URL from your bundler's manifest rather than hard-coding it.
- Frameworks often do this for you. Route-based code splitting tools already emit module preloads for the next navigation. Call it by hand only for things they cannot see.
- Do not preload everything. Idle modules still use bandwidth and memory. Trigger it on likely intent (hover, focus, visibility), not on page load for every route.
React.lazypairs well: callpreloadModulefor the chunk, then render the lazy component when needed. Seelazy.