preinitModuleLink for this heading

January 6, 2025 · View on GitHub

Note

React-based frameworks frequently handle resource loading for you, so you might not have to call this API yourself. Consult your framework’s documentation for details.

preinitModule lets you eagerly fetch and evaluate an ESM module.

preinitModule("https://example.com/module.js", {as: "script"});

Reference
- preinitModule(href, options)
Usage
- Preloading when rendering
- Preloading in an event handler

The preinitModule function provides the browser with a hint that it should start downloading and executing the given module, which can save time. Modules that you preinit are executed when they finish downloading.

Parameters Link for Parameters

href: a string. The URL of the module you want to download and execute.
options: an object. It contains the following properties:
- as: a required string. It must be 'script'.
- _SiteOne_CO_: a string. The CORS policy to use. Its possible values are anonymous and use-credentials.
- integrity: a string. A cryptographic hash of the module, to verify its authenticity.
- nonce: a string. A cryptographic nonce to allow the module when using a strict Content Security Policy.

Returns Link for Returns

preinitModule returns nothing.

Caveats Link for Caveats

Multiple calls to preinitModule with the same href have the same effect as a single call.
In the browser, you can call preinitModule in any situation: while rendering a component, in an Effect, in an event handler, and so on.
In server-side rendering or when rendering Server Components, preinitModule only has an effect if you call it while rendering a component or in an async context originating from rendering a component. Any other calls will be ignored.

Usage Link for Usage

Preloading when rendering Link for Preloading when rendering

Call preinitModule when rendering a component if you know that it or its children will use a specific module and you’re OK with the module being evaluated and thereby taking effect immediately upon being downloaded.

import { preinitModule } from 'react-dom';

function AppRoot() {

  preinitModule("https://example.com/module.js", {as: "script"});

  return ...;

}

If you want the browser to download the module but not to execute it right away, use preloadModule instead. If you want to preinit a script that isn’t an ESM module, use preinit.

Preloading in an event handler Link for Preloading in an event handler

Call preinitModule in an event handler before transitioning to a page or state where the module will be needed. This gets the process started earlier than if you call it during the rendering of the new page or state.

import { preinitModule } from 'react-dom';

function CallToAction() {

  const onClick = () => {

    preinitModule("https://example.com/module.js", {as: "script"});

    startWizard();

  }

  return (

    <button onClick={onClick}>Start Wizard</button>

  );

}