rel="modulepreload"

Baseline2023

Since September 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

Themodulepreload keyword, for therel attribute of the<link> element, provides a declarative way to preemptively fetch amodule script, parse and compile it, and store it in the document's module map for later execution.

Preloading allows modules and their dependencies to be downloaded early, and can also significantly reduce the overall download and processing time.This is because it allows pages to fetch modules in parallel, instead of sequentially as each module is processed and its dependencies are discovered.Note however that you can't just preload everything!What you choose to preload must be balanced against other operations that might then be starved, adversely affecting user experience.

Links withrel="modulepreload" are similar to those withrel="preload".The main difference is thatpreload just downloads the file and stores it in the cache, whilemodulepreload gets the module, parses and compiles it, and puts the results into the module map so that it is ready to execute.

When usingmodulepreload the fetch request mode is alwayscors, and thecrossorigin property is used to determine the requestcredential mode.Ifcrossorigin is set toanonymous or"" (default), then the credentials mode issame-origin, and user credentials such as cookies and authentication are only sent for requests with thesame-origin.Ifcrossorigin is set touse-credentials then the credentials mode isinclude, and user credentials for both single- and cross-origin requests.

Theas attribute is optional for links withrel="modulepreload", and defaults to"script".It can be set to"script" or any script-like destination, such as"audioworklet","paintworklet","serviceworker","sharedworker", or"worker".AnEvent named "error" is fired on the element if any other destination is used.

A browsermay additionally also choose to automatically fetch any dependencies of the module resource.Note however that this is a browser-specific optimization — the only approach to ensure that all browsers will try to preload a module's dependencies is to individually specify them!Further, the events namedload orerror fire immediately following success or failure of loading thespecified resources.If dependencies are automatically fetched, no additional events are fired in the main thread (although you might monitor additional requests in a service worker or on the server).

Examples

Consider thebasic-modules example (live version), introduced in theJavaScript modules guide.

This has a file structure as shown below, consisting of the top level modulemain.js, which statically imports two dependency modulesmodules/canvas.js andmodules/square.js using theimport statement.

index.htmlmain.jsmodules/    canvas.js    square.js

The HTML for the example below shows howmain.js is fetched in a<script> element.Only aftermain.js has loaded does the browser discover and fetch the two dependency modules.

html

<!doctype html><html lang="en-US">  <head>    <meta charset="utf-8" />    <title>Basic JavaScript module example</title>    <script type="module" src="main.js"></script>  </head>  <body></body></html>

The HTML below updates the example to use<link> elements withrel="modulepreload" for the main file and each of the dependency modules.This is much faster because the three modules all start downloading asynchronously and in parallel before they are needed.By the timemain.js has been parsed and its dependencies are known, they have already been fetched and downloaded.

html

<!doctype html><html lang="en-US">  <head>    <meta charset="utf-8" />    <title>Basic JavaScript module example</title>    <link rel="modulepreload" href="main.js" />    <link rel="modulepreload" href="modules/canvas.js" />    <link rel="modulepreload" href="modules/square.js" />    <script type="module" src="main.js"></script>  </head>  <body></body></html>