React Async Script Loader

1.2.0 · active · verified Sun Apr 19

react-async-script is a lightweight React Higher-Order Component (HOC) designed to facilitate the asynchronous loading of external third-party JavaScript scripts within React applications. It is particularly useful for integrating services like Google reCAPTCHA, Google Maps, or other widgets where scripts need to be loaded dynamically without blocking the main thread. The current stable version is 1.2.0, building upon the significant 1.0.0 rewrite that introduced modern React features. The library supports customizing script attributes, automatically registering global callback functions (e.g., for `onload` events), and exposing global variables created by the loaded scripts as props to the wrapped component. It also incorporates React's `forwardRef` for proper ref handling, requiring React version 16.4.1 or higher. While no explicit release cadence is stated, it receives updates to address issues and maintain compatibility with React. Its key differentiator is its focused approach as a simple HOC for script management.

Common errors

```
TypeError: (0, react_async_script__WEBPACK_IMPORTED_MODULE_0__.makeAsyncScriptLoader) is not a function
```
cause Attempting to import `makeAsyncScriptLoader` as a named export from `react-async-script` in an ESM context, but it is a default export.

fix Change your import statement from `import { makeAsyncScriptLoader } from 'react-async-script';` to `import makeAsyncScriptLoader from 'react-async-script';`.
```
Error: Invariant Violation: The `ref` prop is only available for DOM components or using React.forwardRef(). Check the render method of `YourWrappedComponent`.
```
cause This error typically indicates an incompatibility with the React version being used, as `react-async-script` relies on `forwardRef` introduced in React 16.4.1, or an issue with how `ref` is being handled in your own components if you're attempting to forward it further.

fix Verify that your `react` and `react-dom` packages are at least version `16.4.1`. If you are trying to attach a `ref` to your own functional component that is then wrapped by the HOC, ensure that component itself uses `React.forwardRef`.

Warnings

breaking Version 1.0.0 introduced significant breaking changes, altering the HOC's API signature. The wrapped component is now passed as a second function call, the `removeOnMount` option was renamed to `removeOnUnmount` (fixing a typo), and the `exposeFuncs` option was removed entirely as its functionality is now automatic.
Fix: Review the official migration guide for 1.0.0 on the GitHub repository. Update your `makeAsyncScriptLoader` calls to reflect the new `makeAsyncScriptLoader(getScriptUrl, options)(Component)` signature and adjust option names accordingly.
gotcha This library relies on React's `forwardRef` functionality internally, which requires React version `16.4.1` or higher. Using older versions of React will lead to runtime errors related to `ref` handling.
Fix: Ensure your project's `react` and `react-dom` peer dependencies are updated to `^16.4.1` or a more recent compatible version.
gotcha When using the `globalName` option, the library passes `window[globalName]` as a prop to your wrapped component. If the external script has not yet initialized or set this global object when your component first renders, the prop will be `undefined`.
Fix: In your wrapped component, always check if the `globalName` prop (e.g., `this.props.googleMaps`) is truthy before attempting to use it. A common pattern is to perform actions in `componentDidUpdate` when the prop transitions from `undefined` to a defined value.

Install

npm install react-async-script npm
yarn add react-async-script yarn
pnpm add react-async-script pnpm

Imports

makeAsyncScriptLoader
wrong:
```
import { makeAsyncScriptLoader } from 'react-async-script'; // Incorrectly attempts named import for a default export
```
correct:
```
import makeAsyncScriptLoader from 'react-async-script';
```
The `makeAsyncScriptLoader` HOC is exported as the default export in modern (ESM) environments. Using named import syntax will result in an `undefined` value.
makeAsyncScriptLoader (CommonJS)
wrong:
```
const { makeAsyncScriptLoader } = require('react-async-script'); // Incorrectly destructures a default export in CommonJS
```
correct:
```
const makeAsyncScriptLoader = require('react-async-script');
```
For CommonJS environments (e.g., Node.js or older bundlers), the `require` statement directly retrieves the default export. Destructuring it will lead to an `undefined` value or a runtime error.

Quickstart

Demonstrates how to use `makeAsyncScriptLoader` to load an external script (e.g., Google Maps API), handle its `onload` callback, access global variables exposed by the script, and utilize `forwardRef` with the wrapped component. Replace `YOUR_API_KEY` with an actual key.

import React from 'react';
import ReactDOM from 'react-dom';
import makeAsyncScriptLoader from 'react-async-script';

// A placeholder component that would typically consume the loaded script
class MyComponentNeedingScript extends React.Component {
  componentDidUpdate(prevProps) {
    // Access the global object exposed by the loaded script via props
    if (!prevProps.googleMaps && this.props.googleMaps) {
      console.log('Google Maps API is available:', this.props.googleMaps);
      // Example: Initialize a map once the API is loaded
      // new this.props.googleMaps.Map(document.getElementById('map'), { center: {lat: -34, lng: 151}, zoom: 8 });
    }
  }
  render() {
    return (
      <div>
        <p>Loading external script...</p>
        {/* You might render a placeholder or a loading spinner here */}
        <div id="map" style={{ width: '100%', height: '300px' }}></div>
      </div>
    );
  }
}

// Define the script URL, callback name, and the global object name
const SCRIPT_URL = `https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap`;
const CALLBACK_NAME = 'initMap';
const GLOBAL_NAME = 'googleMaps'; // The global object set by the script (e.g., window.googleMaps)

// Wrap your component with the HOC
const GoogleMapsLoader = makeAsyncScriptLoader(SCRIPT_URL, {
  callbackName: CALLBACK_NAME,
  globalName: GLOBAL_NAME,
  removeOnUnmount: true, // Optional: remove script tag when component unmounts
})(MyComponentNeedingScript);

class App extends React.Component {
  constructor(props) {
    super(props);
    this._myRef = React.createRef();
  }

  componentDidMount() {
    console.log("Ref to MyComponentNeedingScript instance:", this._myRef.current);
  }

  handleScriptLoad = () => {
    console.log("External Google Maps script has finished loading!");
    // Any post-load actions can be performed here
  };

  render() {
    return (
      <div>
        <h1>React Async Script Loader with Google Maps</h1>
        <GoogleMapsLoader ref={this._myRef} asyncScriptOnLoad={this.handleScriptLoad} />
      </div>
    );
  }
}

// Ensure a root element exists for React to render into
const rootElement = document.getElementById('root');
if (!rootElement) {
  const div = document.createElement('div');
  div.id = 'root';
  document.body.appendChild(div);
}

ReactDOM.render(<App />, rootElement);

// Simulate the global callback function that the Google Maps API calls
// This must be a global function for the script to find it
window[CALLBACK_NAME] = () => {
  console.log(`Global callback '${CALLBACK_NAME}' executed.`);
  // For Google Maps, the 'google.maps' global becomes available after this.
  // The HOC will pick this up and pass 'googleMaps' as a prop.
};

view raw JSON →