DEV Community: Sachith Siriwardana

Handling React.lazy Chunk Load Errors After Deployment

Sachith Siriwardana — Sun, 18 Oct 2026 06:19:49 +0000

Why old browser tabs request missing chunks—and how react-lazy-chunk-recover handles the failure without a reload loop.

A user leaves a React app open during a deployment. Hours later, they visit a lazy-loaded route for the first time. Their old tab requests a chunk the new deployment no longer serves. The route fails, even though it works in a fresh tab.

For example, the old tab might request Reports.a1b2.js after the server has switched to Reports.c3d4.js. The hashes are illustrative; the missing-file failure is the point. Vite documents this deployment failure mode.

I built and published react-lazy-chunk-recover to handle this case inside a React.lazy component loader. It recognizes likely chunk-load errors, allows one guarded reload, and passes a repeat failure to your Error Boundary. The package includes TypeScript declarations, lists React as a peer dependency, and has no direct runtime dependencies.

Why the usual `React.lazy` setup cannot recover on its own

React.lazy waits until the first render to call your loader. While the import is pending, <Suspense> shows a fallback. If the import rejects, React sends the error to the nearest Error Boundary. React also caches the loader promise and its result, so another render of the same lazy component does not simply start a new import. React describes each behavior in its lazy reference.

An Error Boundary can explain the failure. It cannot, by itself, update the old tab's asset references. A reload may do that by fetching the current HTML and application bundle—but only if your deployment serves them correctly. An unconditional reload can trap the user when the error persists.

The recovery code therefore needs two decisions: Is this likely a chunk-load error? And has this tab already tried to recover?

How react-lazy-chunk-recover works

The package recognises dynamic-import messages such as Failed to fetch dynamically imported module and ChunkLoadError. For a matching failure, it reads a sessionStorage guard. If no guard exists, it writes one and calls window.location.reload(). If a guard already exists, it throws the error to React. A successful load clears the guard, so a later deployment can get its own recovery attempt.

If the browser blocks sessionStorage, the package throws the error instead of starting a reload it cannot limit. During server-side rendering, it skips browser storage and page reloads; it rethrows the original import error.

Let's use it on a lazy route

Install the package:

npm install react-lazy-chunk-recover

Then replace the React.lazy call. Keep the lazy component at module scope, as React recommends:

import { Suspense } from 'react';
import { lazyWithRetry } from 'react-lazy-chunk-recover';

const Reports = lazyWithRetry(() => import('./Reports'), {
  moduleKey: 'reports',
});

export function ReportsRoute() {
  return (
    <Suspense fallback={<p>Loading reports…</p>}>
      <Reports />
    </Suspense>
  );
}

moduleKey gives this lazy loader its own guard. Use a stable, unique value for each logical lazy-loaded component—for example, reports and settings. Keep the value the same across renders and deployments; do not generate a random key or reuse one key for unrelated components. Without moduleKey, lazy components share the default guard, and one successful load can clear another component's recovery attempt.

Keep your Error Boundary around the route. <Suspense> handles the pending import; the Error Boundary handles a non-chunk error or a failed recovery. lazyWithRetry does not export an Error Boundary or replace the one your app already uses.

This wrapper targets components loaded through React.lazy. It is not a replacement for React Router's separate route-module lazy API or for every dynamic import in an application.

Configure retries for the failure you actually see

The default retries value is 0. That is deliberate: a second request for a deleted hashed file usually gets the same 404.

If your telemetry also shows brief network interruptions, allow a small number of in-place retries:

const Reports = lazyWithRetry(() => import('./Reports'), {
  moduleKey: 'reports',
  retries: 2,
  retryDelayMs: 250,
});

The loader makes up to two extra attempts, with the wait doubling after each attempt. It only enters the reload path if a recognised failure remains. Start with the default; add retries when your production errors justify the extra delay.

For an application that publishes a trusted, current asset manifest, getFreshModule offers one alternate import attempt before the reload. Your application must supply the URL and verify that the returned module is compatible with the running app. The package cannot derive a new hashed URL from the old import error. I would not enable that path without a defined manifest contract and a test that spans two builds.

Test it like a real deployment

Use a staging environment, not production. In this test, build A is the version already running in an open tab, and build B is the newer version on the server. Pick one lazy route, such as /reports. You want to see whether the old tab can reach the working route after its old chunk disappears.

First run: recovery succeeds

Deploy build A. Open the app and leave that tab on a different route; do not open /reports yet. Check the Network panel to make sure the route's chunk has not already been prefetched.
Deploy build B without refreshing the old tab. In staging, make build A's /reports chunk unavailable. If your host retains old files, block that exact old chunk URL in your browser's request-blocking tools instead.
In the old tab, open /reports. The request for build A's chunk should fail. Expect one full-page reload, followed by the /reports page from build B.
Use the page, not just its heading. Confirm its important backend request or action still works with build B.

Second run: recovery cannot finish

Start again with a clean browser session and repeat the setup, but make build B's /reports chunk fail too. Expect at most one automatic reload. After the second failure, your Error Boundary should appear instead of another reload.

Finally, refresh /reports directly to confirm your server serves the app on a nested URL. In automated tests, also simulate blocked sessionStorage; the package should throw the error rather than reload without a guard.

Record the chunk-load failure, the attempted reload, and whether the route works against the current backend afterwards. The reload alone does not confirm recovery.

Plan for deployment compatibility too

The wrapper handles a failure after it reaches a lazy component. Your release process also needs to decide whether an old client may keep running:

Retain old hashed assets only when the old client remains compatible and safe. An incompatible API change or urgent security fix may require old tabs to update instead.
Let browsers revalidate the HTML entry point. Vite recommends Cache-Control: no-cache for HTML in this scenario.
If you use Vite, review its vite:preloadError event for dynamic-import failures outside this wrapper.
Confirm that a full-page reload works on every client-side route.

If a release requires every open tab to update, use an explicit app-version or update policy. This package only reacts when a wrapped lazy import fails; it cannot force an update while old chunks continue to load. If the current build still cannot load the route, the package passes the failure to your Error Boundary instead of refreshing forever.

Final thoughts

A deployment can change more than file names. It can change API contracts, fix a critical bug, or remove vulnerable client code. Keeping old chunks available may avoid a 404 while leaving an old tab on a version you no longer want running.

That is why I built react-lazy-chunk-recover: when a wrapped lazy import fails, the tab gets one guarded chance to load the current build. If it still fails, your Error Boundary takes over. The package does not replace a version policy for releases that must retire every old client.

If you face stale-chunk failures, try the package on one lazy route and reproduce the two-build deployment described above. Check the route's backend interactions after the reload, not just its loading state. A reload is an attempt; a working route on the current build is recovery.

I would be interested to hear how your app handles breaking deployments and what chunk-load message your browser or bundler produces. If you try the package, share those details and whether the route worked after the reload. That feedback can help shape the next release.

ENJOY YOUR CODING! 🚀

Introduction to GPGPU Computing with CUDA and C++

Sachith Siriwardana — Tue, 19 Oct 2021 13:14:45 +0000

Introduction

Nowadays some software programs become complex and need huge computation power with sequential programming this is a problem but with parallel processing, the speed of the programs can be increased because it exploits the parallelism provided by the multi-core architecture. So developers Shift in the traditional paradigm of sequential programming, towards parallel processing when there is a need for huge parallelism....

Read Full article

Neutralinojs + React Starter Template

Sachith Siriwardana — Fri, 01 May 2020 18:32:31 +0000

What is NeutralinoJs

Neutralino is a lightweight and portable application development framework. It lets you develop cross-platform applications using JavaScript/Typescript, HTML and CSS.This framework is also similar to Electron, Nw.js, and a few more.

The key difference of Neutralino is that it won’t run top of Chromium and NodeJs.

Why NeutralinoJs?

Let’s see what NeutralinoJs docs says

“ In Electron and NW.js you have to install NodeJs and hundreds of dependency libraries. Embedded Chromium and Node creates large overhead and makes even simple apps like “hello world” considerable in size. Neutralino offers a lightweight and portable SDK which is an alternative for Electron and NW.js also with many advantages. ”

With the rough idea that I have given above on NeutralinoJs, let’s focus on the topic which I am going to discuss from here. 😉
From now onward I may refer NeutralinoJs as Neu.

Legacy Neu-React template

Let’s talk about the old neu-react template. It was developed 2 years ago using an older version of NeutralinoJs. It transpile the javascript ES6+ code to ES5 each and every time when application started. Either it’s development or production there is no difference, it needs to transpile the code every time which makes it a bit slow.

Also if you are going to use React with NeutralinoJs most of the time you are familiar with React, so you are familiar with component-based project structure but the template was not that much supporting the component-based structure.
Thus, there are some differences between these two

The story of developing a new template

This heading is the main reason for me to write this article. Most of the contribution to developing this new template was done by me. 😎

The real reason that allowed me to develop this project was a hackathon organized by 99X Technology called Hacktitude. Therefore, I participated and got selected for the top 10 contributors. From then on I was able to develop the project with the help of my mentors.

So that’s how I got the opportunity to develop this awesome project and I’m really happy that I was able to contribute to NeutralinoJs.

That’s the long story in short 😉

here is the new template 😎.

neutralinojs / neutralinojs-react

React starter project for Neutralinojs

Comparison between legacy and new template

New template is more supporting component based structure than legacy template.
While developing with the legacy, if you refresh the browser after a while you may see the “unable to connect” error but, with a new template you will never experience that issue. So while developing you can use the below command to avoid that and after the execution of the command you can open the app in browser mode, so you can have uninterrupted development experience.

npm start
In legacy ES6+ code needs to transpile to ES5 every time when application starts so it’s a bit slow.but with new template it transpile the code with support of webpack,when the application is built. so it’s not going to transpile the code at runtime.and code was also optimized with this method.
New template App folder size also became smaller than the legacy because it didn’t include the babel.js.just babel.js take 1888 Kb.

Legacy uses the older version of NeutralinoJs but New template uses the latest version(1.3.0).
If you are going to use a version control system like Github .You can use an automated dependency update tool like dependabot to update react,babel..etc .But with legacy you can’t automate the process. because those react,react-dom,babel files are manually placed inside the App/assets folder.with the new template this was also fixed.

NeutralinoJs CLI

You can easily create Neutralino applications with several pre-build templates. like a new Neutralino-react template there are other templates which you can tryout.

you can refer to the NeutralinoJs docs for more detailed examples for creating applications using Neu-CLI.also at the end of this post i am also going to tell you how to create Neutralino-react template using Neu-CLI.

Let’s say you are not going to use Neu-CLI and the Neutralino-react template to create you’r Neutralino-react project, then you have to spend some time configuring the project 😕 . so,it’s really easy to use neu-cli or template for you project rather than going through the configurations. 😎

How to create Neutralino-React project using Neu-CLI

It’s really simple to create a new project using neu-cli.

Open your terminal(cmd,terminal,git bash..etc) and cd into the location where you would like to create your project.

Step 1 : Let’s install Neu-cli
npm i -g @neutralinojs/neu

Step 2 : * Let’s create the app.you can give any name for myapp*
neu create myapp --template react

Step 3 : * Let’s cd into the project folder and build the app*
cd myapp && neu build

After successful build you will see this massage in the terminal

Step 4 : Let’s open NeutralinoJs executable file (open corresponding file for you OS)

If you do everything correctly when you open the executable file.you will see this 🚀

Okay, now you know how to create an application using Neu-React template. 😎

This is my first article. I really hope you’ve liked this article and I am very keen on hearing your thoughts about it. Just give this article a comment and I’ll be more than happy to reply.

ENJOY YOUR CODING! 🚀.