Retry dynamic imports

> Retry dynamic imports using cache busting and exponential backoff

Did you know that the [HTML spec][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][so-answer] after receiving mysterious bug reports from users before I found the [WHATWG issue][html spec 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.

[html spec]: https://html.spec.whatwg.org/#fetch-a-single-module-script
[html spec issue]: https://github.com/whatwg/html/issues/6768
[so-answer]: https://stackoverflow.com/a/76200536/200987

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?

1. Open the demo application that is deployed on Github Pages
2. Open DevTools and refresh the page
3. Right click on the ExpensiveComponent.\* url and choose to block it
4. Refresh and see the network requests fail in the Network tab of DevTools
5. 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

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

$3

> Works in any framework

`typescript
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.

$3


The createDynamicImportWithRetry factory recently got a new feature that allows you to pass in _your own custom strategy_ for dealing with imports, instead of the pre-defined ones. One specific use-case, shown in the tests, is that this opens up for supporting retries of _dynamic_ import paths.

`typescript
// ONE-TIME SETUP
const moduleSpecifierSymbol = Symbol()
const lookupUsingSymbolInImporter: UrlStrategy = (_, importer) =>
moduleSpecifierSymbol in importer
? String(importer[moduleSpecifierSymbol])
: null;

const customRetryImport = createDynamicImportWithRetry(3, {strategy: lookupUsingSymbolInImporter})
// ...

// USE
// This can now be used with dynamically created paths like this
const path = readFromUser();
const importer = Object.assign(() => import(path), {
[moduleSpecifierSymbol]: path,
});

await customRetryImport(importer)
`

$3

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][issue-1], 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 :)

$3

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

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

const App = () => (

Loading...