lazy-retry 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+# lazy-retry
+
+> React.lazy wrapper that auto-recovers from chunk 404s after deployment.
+
+When you deploy a new version of your app, old chunk hashes are gone from the server. Users who have the old page open get a `Loading chunk N failed` error the next time they lazy-load a route. This package catches that, does a **single page reload** (debounced to 30 s via `sessionStorage`), and gets them onto the new bundle — silently.
+
+## Install
+
+```bash
+npm install lazy-retry
+# or
+pnpm add lazy-retry
+```
+
+React 17+ is a peer dependency.
+
+## Usage
+
+```tsx
+// Before
+const Dashboard = React.lazy(() => import('./pages/Dashboard'));
+
+// After — one word change
+import { lazyWithRetry } from 'lazy-retry';
+
+const Dashboard = lazyWithRetry(() => import('./pages/Dashboard'));
+```
+
+Wrap your routes in a `<Suspense>` and an `ErrorBoundary` as you normally would. `lazyWithRetry` handles the chunk-404 case; the `ErrorBoundary` handles anything else.
+
+```tsx
+<ErrorBoundary fallback={<ErrorPage />}>
+  <Suspense fallback={<Spinner />}>
+    <Dashboard />
+  </Suspense>
+</ErrorBoundary>
+```
+
+## How it works
+
+1. Calls your import factory normally.
+2. If the import throws and the error message matches known chunk-load failure patterns (Webpack, Vite, Safari), it checks `sessionStorage` for a recent reload timestamp.
+3. If no reload has happened in the last 30 s, it stamps the timestamp and calls `window.location.reload()`.
+4. If a reload already happened recently (user is on a bad connection, not a stale chunk), it re-throws so your `ErrorBoundary` can show a proper fallback.
+
+## API
+
+### `lazyWithRetry(factory)`
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `factory` | `() => Promise<{ default: ComponentType }>` | Same signature as `React.lazy` |
+
+Returns the same type as `React.lazy` — a lazy component you use identically.
+
+### `isChunkError(err)` *(exported for testing)*
+
+Returns `true` if the error looks like a chunk load failure. Covers Webpack, Vite, and Safari error messages.
+
+### `hasReloadedRecently()` *(exported for testing)*
+
+Returns `true` if a reload was recorded in `sessionStorage` within the last 30 s.
+
+## Caveats
+
+- Calls `window.location.reload()` — SSR/Node environments should not use this package.
+- Only one auto-reload per 30 s per browser tab. Subsequent failures surface to your `ErrorBoundary`.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,19 @@
+import { ComponentType, lazy } from 'react';
+
+type ImportFactory<T extends ComponentType<unknown>> = () => Promise<{
+    default: T;
+}>;
+declare function hasReloadedRecently(): boolean;
+declare function isChunkError(err: unknown): boolean;
+/**
+ * Drop-in replacement for React.lazy that recovers from chunk 404s after
+ * a new deployment. On failure it does a single full-page reload (debounced
+ * to 30 s via sessionStorage) then re-throws so an ErrorBoundary can render
+ * a fallback if reloading doesn't help.
+ *
+ * @example
+ * const MyPage = lazyWithRetry(() => import('./MyPage'));
+ */
+declare function lazyWithRetry<T extends ComponentType<unknown>>(factory: ImportFactory<T>): ReturnType<typeof lazy<T>>;
+
+export { hasReloadedRecently, isChunkError, lazyWithRetry };

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { ComponentType, lazy } from 'react';
+
+type ImportFactory<T extends ComponentType<unknown>> = () => Promise<{
+    default: T;
+}>;
+declare function hasReloadedRecently(): boolean;
+declare function isChunkError(err: unknown): boolean;
+/**
+ * Drop-in replacement for React.lazy that recovers from chunk 404s after
+ * a new deployment. On failure it does a single full-page reload (debounced
+ * to 30 s via sessionStorage) then re-throws so an ErrorBoundary can render
+ * a fallback if reloading doesn't help.
+ *
+ * @example
+ * const MyPage = lazyWithRetry(() => import('./MyPage'));
+ */
+declare function lazyWithRetry<T extends ComponentType<unknown>>(factory: ImportFactory<T>): ReturnType<typeof lazy<T>>;
+
+export { hasReloadedRecently, isChunkError, lazyWithRetry };

package/dist/index.js

@@ -0,0 +1,65 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  hasReloadedRecently: () => hasReloadedRecently,
+  isChunkError: () => isChunkError,
+  lazyWithRetry: () => lazyWithRetry
+});
+module.exports = __toCommonJS(index_exports);
+var import_react = require("react");
+var RELOAD_KEY = "lazy-retry:reloaded";
+var DEBOUNCE_MS = 3e4;
+function hasReloadedRecently() {
+  const raw = sessionStorage.getItem(RELOAD_KEY);
+  if (!raw) return false;
+  return Date.now() - parseInt(raw, 10) < DEBOUNCE_MS;
+}
+function markReloaded() {
+  sessionStorage.setItem(RELOAD_KEY, String(Date.now()));
+}
+function isChunkError(err) {
+  if (!(err instanceof Error)) return false;
+  return /loading chunk [\w]+ failed|failed to fetch dynamically imported module|importing a module script failed/i.test(
+    err.message
+  );
+}
+function lazyWithRetry(factory) {
+  return (0, import_react.lazy)(async () => {
+    try {
+      return await factory();
+    } catch (err) {
+      if (isChunkError(err) && !hasReloadedRecently()) {
+        markReloaded();
+        window.location.reload();
+        return new Promise(() => {
+        });
+      }
+      throw err;
+    }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  hasReloadedRecently,
+  isChunkError,
+  lazyWithRetry
+});

package/dist/index.mjs

@@ -0,0 +1,38 @@
+// src/index.ts
+import { lazy } from "react";
+var RELOAD_KEY = "lazy-retry:reloaded";
+var DEBOUNCE_MS = 3e4;
+function hasReloadedRecently() {
+  const raw = sessionStorage.getItem(RELOAD_KEY);
+  if (!raw) return false;
+  return Date.now() - parseInt(raw, 10) < DEBOUNCE_MS;
+}
+function markReloaded() {
+  sessionStorage.setItem(RELOAD_KEY, String(Date.now()));
+}
+function isChunkError(err) {
+  if (!(err instanceof Error)) return false;
+  return /loading chunk [\w]+ failed|failed to fetch dynamically imported module|importing a module script failed/i.test(
+    err.message
+  );
+}
+function lazyWithRetry(factory) {
+  return lazy(async () => {
+    try {
+      return await factory();
+    } catch (err) {
+      if (isChunkError(err) && !hasReloadedRecently()) {
+        markReloaded();
+        window.location.reload();
+        return new Promise(() => {
+        });
+      }
+      throw err;
+    }
+  });
+}
+export {
+  hasReloadedRecently,
+  isChunkError,
+  lazyWithRetry
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "lazy-retry",
+  "version": "0.1.0",
+  "description": "React.lazy wrapper that auto-reloads on chunk 404s after deployment",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": ["react", "lazy", "retry", "chunk", "404", "deployment", "code-splitting"],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=17.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^14.0.0",
+    "@types/react": "^18.0.0",
+    "jsdom": "^24.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}