English

react
lazy
suspense

Use React.lazy with confidence: A safe way to load components when iterating fast

React.lazy is a great way to load components on demand and improve the performance of your app. However, sometimes it can lead to some issues like "ChunkLoadError" and "Loading chunk failed".

Gao

Founder

7/26/20243 min read

Stop wasting weeks on user auth

Launch secure apps faster with Logto. Integrate user auth in minutes, and focus on your core product.

Get started

The dilemma

Nowadays, software development is moving faster under the popular "move fast and break things" philosophy. No judgment here - it's just the way things are. However, this fast pace can sometimes lead to issues, especially when it comes to loading components in React.

If you are working on a project that uses React.lazy to load components on demand, you might have encountered some issues like ChunkLoadError and Loading chunk failed. Here are some possible reasons:

There's a network issue, for example, the user's internet connection is slow or unstable.
The user is on an obsolete version of the app, and the browser is trying to load a chunk that doesn't exist anymore.

Usually, a simple refresh of the page can solve the problem, but it's not a great experience for the user. Imagine if a white screen appears when the user is navigating to another route - it's not a good look for your app.

Can we balance the need for speed with the need for a smooth user experience? Sure. Let me show you how (with TypeScript, of course).

The solution

A brute force solution can be to save all the versions of the chunks in the server, thus no more the "missing chunk" issue. As your app grows, this solution can become unfeasible due to increasing disk space requirements, and it still doesn't solve the network issue.

Given the fact that a retry or a refresh can solve the problem, we can implement these solutions in our code. Since the issue usually happens when the user is navigating to another route, we can solve it even without the user noticing. All we need to do is to build a wrapper around the React.lazy function that will handle the retries and the refreshes.

There are already some great articles on how to implement this kind of solution, so I'll focus on the idea and inner workings of the solution.

Create the wrapper

The first step is to create a wrapper around the React.lazy function:

Handle the retries

For network issues, we can handle the retries by wrapping the importFunction in a tryImport function:

Looks simple, right? You can also implement the exponential backoff algorithm to handle the retries more efficiently.

Handle the refreshes

For the obsolete version issue, we can handle the refreshes by catching the error and refreshing the page:

However, this implementation is very dangerous, as it may cause an infinite loop of refreshes when the error cannot be solved by a refresh. Meanwhile, the app state will be lost during the refresh. So we need the help of sessionStorage to store the message that we've tried to refresh the page:

Now, when we catch the error from the safeLazy function, we know it is something that cannot be solved by a refresh.

Multiple lazy components on the same page

There's still a hidden pitfall with the current implementation. If you have multiple lazy components on the same page, the infinite loop of refreshes can still happen because other components may reset the sessionStorage value. To solve this issue, we can use a unique key for each component:

Now, each component will have its own sessionStorage key, and the infinite loop of refreshes will be avoided. We can continue to nitpick the solution, for example:

Gather all the keys in an array, thus only one storage key is needed.
Set a refresh limit to refresh the page more than one time before throwing an error.

But I think you get the idea. A comprehensive TypeScript solution with tests and configurations is available in the GitHub repository. I've also published the react-safe-lazy package on NPM, so you can use it in your project right away.

Conclusion

Software development is a delicate work, and even the smallest details can take effort to resolve. I hope this article can help you to gracefully handle the issues with React.lazy and improve the user experience of your app.

The dilemma#

The solution#

Create the wrapper#

Handle the retries#

Handle the refreshes#

Multiple lazy components on the same page#

Conclusion#

The dilemma#

The solution#

Create the wrapper#

Handle the retries#

Handle the refreshes#

Multiple lazy components on the same page#

Conclusion#

The dilemma

The solution

Create the wrapper

Handle the retries

Handle the refreshes

Multiple lazy components on the same page

Conclusion

The dilemma

The solution

Create the wrapper

Handle the retries

Handle the refreshes

Multiple lazy components on the same page

Conclusion