@fatso83/retry-dynamic-import

Retry dynamic imports

Retry dynamic imports using cache busting and exponential backoff

Did you know that the HTML spec demands that failed dynamic import resolutions are to be cached? Turns out, most people do not and only get to know this once they deploy apps using dynamic imports to production and start seeing weird errors after some time. Neither did I, and I ended up doing a whole lot of debugging and googling after receiving mysterious bug reports from users before I found the WHATWG issue for exactly this situation. Since this has been at a stand still since 2021, I ended up creating this library to work around the issues.

This package was originally a fork of Alon Mizrahi's work, but the new code no longer uses Alon's approach, which was relying on parsing Chromium specific error messages, and the new approach works in Firefox and other browsers as well.

Completed improvements:

• ✅ unit tests
• ✅ support non-Chromium browsers (like Firefox)
• ✅ tree shakeable (does not pull in React if you just use the non-react bits)
• ✅ speed up resolution on afflicted clients by not waiting for first cache busting attempt
• ✅ fix exports to work with Typescript using both NodeNext and "classic" module resolution
• ❌ dual exports (currently just ESM), shout out if you want it (we already produce the *.cjs files)

Why not just catch a failure and reload the page?

While that works fine in Firefox, in Chromium based browsers (Edge, Chrome, ...) a failed module import is cached and that failure is sticky: it is not retried on reload or over browser restarts (per Chrome 113). That is real failures, not DevTool URL blocking, which is not sticky, for whatever reason.

Demo?

• Open the demo application that is deployed on Github Pages
• Open DevTools and refresh the page
• Right click on the ExpensiveComponent.* url and choose to block it
• Refresh and see the network requests fail in the Network tab of DevTools
• Unblock the url and see it work again

If you want to see the sticky behavior mentioned above, setup Charles Proxy and its "Breakpoints" feature to be able to selectively block or accept requests. Works great!

Limitations

Transitive imports: read this article to understand the details of how dynamic imports might fail and how this solves some of these use cases. One use case it cannot solve is if a transitive dependency should fail to load.

Installing

npm i @fatso83/retry-dynamic-import

Usage

The package has two main exports

export const dynamicImportWithRetry // default implementation with 5 retries
export const createDynamicImportWithRetry  // factory to make your own version of dynamicImportWithRetry

Vanilla JS util

Works in any framework

import { dynamicImportWithRetry } from "@fatso83/retry-dynamic-import";
const myModule = dynamicImportWithRetry(() => import("./my-module")); // this works regardless of framework, lib, etc

See the unit tests or the implementation for what options it supports.

React utility

Additionallly, you can import reactLazyWithRetry from '@fatso83/retry-dynamic-import/react-lazy' for a utility that can be used instead of React.lazy() for lazy imports with retries. In version 1.* this was exposed on root, but most bundlers were unable to tree-shake React, so I decided to make a breaking change for version 2 that exposes it as subpath export.

React is an _optional dependency of this package_, which means you can use it with Svelte or VanillaJS without pulling in extra dependencies by specifying npm install --omit=optional, but if you use the react-lazy sub-export you will of course need to have React in your dependency tree :)

reactLazyWithRetry

Thin wrapper around the above, calling out to React.lazy()

const LazyAbout = reactLazyWithRetry(() => import("./components/About"));
const LazyHome = reactLazyWithRetry(() => import("./components/Home"));

const App = () => (
  <Router>
    <Suspense fallback={<div>Loading...</div>}>
      <Routes>
        <Route path="/" element={<LazyHome />} />
        <Route path="/about" element={<LazyAbout />} />
      </Routes>
    </Suspense>
  </Router>
);

Contributing

Please do!

• Run tests: DEBUG=dynamic-import:* npm t -- --watch (the env var is just for verbose output)