react-build-reload 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Satyam shah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# react-build-reload
+
+React library for detecting when a new frontend build is available and helping the app refresh safely.
+
+## Website
+
+Homepage: [react-refresh-website.satyamshah.workers.dev](https://react-refresh-website.satyamshah.workers.dev)
+
+## Install
+
+```bash
+npm install react-build-reload
+```
+
+React is a peer dependency. The consuming app must provide React and React DOM.
+
+## Quick Start
+
+Generate the version file before building your app:
+
+```bash
+npx react-build-reload generate
+```
+
+This creates `public/build-version.json`.
+
+Add the watcher near the root of your app:
+
+```tsx
+import { BuildReloadWatcher } from "react-build-reload";
+
+export function App() {
+  return (
+    <>
+      <BuildReloadWatcher
+        versionUrl="/build-version.json"
+        checkInterval={60_000}
+        reloadMode="prompt"
+      />
+      <MainApp />
+    </>
+  );
+}
+```
+
+The generated version file looks like this:
+
+```json
+{
+  "buildId": "abc123-20260530123000",
+  "version": "1.0.0",
+  "builtAt": "2026-05-30T12:30:00.000Z",
+  "environment": "production"
+}
+```
+
+When `buildId` changes, the library can show a prompt, reload automatically, or call your callback.
+
+## Defaults
+
+```tsx
+<BuildReloadWatcher
+  versionUrl="/build-version.json"
+  checkInterval={60000}
+  reloadMode="prompt"
+  reloadOnChunkError={true}
+/>
+```
+
+## Hook Usage
+
+```tsx
+import { useBuildReload } from "react-build-reload";
+
+function CustomReloadNotice() {
+  const { isNewBuildAvailable, reloadApp } = useBuildReload({
+    reloadMode: "manual"
+  });
+
+  if (!isNewBuildAvailable) return null;
+
+  return <button onClick={reloadApp}>Refresh now</button>;
+}
+```
+
+## Documentation
+
+- [Getting started](docs/getting-started.md)
+- [API reference](docs/api-reference.md)
+- [Version file](docs/version-file.md)
+- [Usage examples](docs/usage-examples.md)
+- [Roadmap](docs/roadmap.md)
+
+## Scope
+
+This package handles runtime build checks in React apps and includes a small CLI to create `build-version.json`. It does not provide Vite/Webpack/Next.js plugins or manage service workers.
+
+## Author
+
+Created by [Satyam Shah](https://github.com/satyam-shah-gt).
+
+## Free to Use
+
+`react-build-reload` is free to use under the MIT license.
+
+## No Warranty
+
+This package is provided as-is, without any warranty. The author is not liable for any damages, data loss, downtime, or other issues caused by using this package. Review and test it in your own environment before using it in production.
+
+## Contributing
+
+Contributions are welcome. Please open an issue or pull request on the repository:
+
+[github.com/satyam-shah-gt/react-build-reload](https://github.com/satyam-shah-gt/react-build-reload)
+
+Before submitting changes, run:
+
+```bash
+npm run typecheck
+npm test
+npm run build
+```

package/bin/react-build-reload.js

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  writeFileSync
+} from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const DEFAULT_OUT = "public/build-version.json";
+
+function printHelp() {
+  console.log(`react-build-reload
+
+Usage:
+  react-build-reload generate [options]
+
+Options:
+  --out <path>           Output file path. Default: ${DEFAULT_OUT}
+  --build-id <id>        Build ID to write. Defaults to env/git/timestamp data.
+  --version <version>    App version. Defaults to package.json version when found.
+  --environment <name>   Environment name. Defaults to NODE_ENV or production.
+  --no-git               Skip git metadata lookup.
+  --help                 Show help.
+
+Example:
+  react-build-reload generate --out public/build-version.json
+`);
+}
+
+function parseArgs(args) {
+  const options = {
+    command: "generate",
+    out: DEFAULT_OUT,
+    buildId: undefined,
+    version: undefined,
+    environment: undefined,
+    includeGit: true,
+    help: false
+  };
+
+  const pending = [...args];
+
+  if (pending[0] && !pending[0].startsWith("-")) {
+    options.command = pending.shift();
+  }
+
+  for (let index = 0; index < pending.length; index += 1) {
+    const arg = pending[index];
+
+    switch (arg) {
+      case "--out":
+        options.out = readRequiredValue(pending, ++index, "--out");
+        break;
+      case "--build-id":
+        options.buildId = readRequiredValue(pending, ++index, "--build-id");
+        break;
+      case "--version":
+        options.version = readRequiredValue(pending, ++index, "--version");
+        break;
+      case "--environment":
+        options.environment = readRequiredValue(pending, ++index, "--environment");
+        break;
+      case "--no-git":
+        options.includeGit = false;
+        break;
+      case "--help":
+      case "-h":
+        options.help = true;
+        break;
+      default:
+        throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function readRequiredValue(args, index, optionName) {
+  const value = args[index];
+
+  if (!value || value.startsWith("-")) {
+    throw new Error(`${optionName} requires a value.`);
+  }
+
+  return value;
+}
+
+function readPackageJson(cwd) {
+  const packagePath = resolve(cwd, "package.json");
+
+  if (!existsSync(packagePath)) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(readFileSync(packagePath, "utf8"));
+  } catch {
+    throw new Error(`Could not parse ${packagePath}.`);
+  }
+}
+
+function readGitValue(cwd, args) {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+function readGitInfo(cwd) {
+  const commit = readGitValue(cwd, ["rev-parse", "HEAD"]);
+  const shortCommit = readGitValue(cwd, ["rev-parse", "--short", "HEAD"]);
+  const branch = readGitValue(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const status = readGitValue(cwd, ["status", "--porcelain"]);
+
+  if (!commit && !shortCommit && !branch) {
+    return undefined;
+  }
+
+  return {
+    commit,
+    shortCommit,
+    branch,
+    dirty: Boolean(status)
+  };
+}
+
+function readEnvBuildId(env) {
+  return (
+    env.BUILD_ID ||
+    env.VITE_BUILD_ID ||
+    env.REACT_APP_BUILD_ID ||
+    env.GITHUB_SHA ||
+    env.VERCEL_GIT_COMMIT_SHA ||
+    env.CF_PAGES_COMMIT_SHA ||
+    env.COMMIT_SHA
+  );
+}
+
+function createBuildId({ explicitBuildId, env, gitInfo, builtAt }) {
+  if (explicitBuildId?.trim()) {
+    return explicitBuildId.trim();
+  }
+
+  const envBuildId = readEnvBuildId(env);
+
+  if (envBuildId?.trim()) {
+    return envBuildId.trim();
+  }
+
+  const timestamp = builtAt.replace(/\D/g, "").slice(0, 14);
+
+  if (gitInfo?.shortCommit) {
+    return `${gitInfo.shortCommit}-${timestamp}`;
+  }
+
+  return `build-${timestamp}`;
+}
+
+function createBuildInfo(options, cwd = process.cwd(), env = process.env) {
+  const packageJson = readPackageJson(cwd);
+  const builtAt = new Date().toISOString();
+  const git = options.includeGit ? readGitInfo(cwd) : undefined;
+  const buildId = createBuildId({
+    explicitBuildId: options.buildId,
+    env,
+    gitInfo: git,
+    builtAt
+  });
+
+  if (!buildId.trim()) {
+    throw new Error("Generated buildId is empty.");
+  }
+
+  const buildInfo = {
+    buildId,
+    version: options.version || packageJson.version || "0.0.0",
+    builtAt,
+    environment: options.environment || env.NODE_ENV || "production"
+  };
+
+  if (packageJson.name) {
+    buildInfo.name = packageJson.name;
+  }
+
+  if (git) {
+    buildInfo.git = git;
+  }
+
+  return buildInfo;
+}
+
+function writeBuildInfo(buildInfo, outPath, cwd = process.cwd()) {
+  const absoluteOutPath = resolve(cwd, outPath);
+
+  mkdirSync(dirname(absoluteOutPath), { recursive: true });
+  writeFileSync(absoluteOutPath, `${JSON.stringify(buildInfo, null, 2)}\n`, "utf8");
+
+  return absoluteOutPath;
+}
+
+function run(args = process.argv.slice(2), cwd = process.cwd(), env = process.env) {
+  const options = parseArgs(args);
+
+  if (options.help) {
+    printHelp();
+    return 0;
+  }
+
+  if (options.command !== "generate") {
+    throw new Error(`Unknown command: ${options.command}`);
+  }
+
+  const buildInfo = createBuildInfo(options, cwd, env);
+  const outPath = writeBuildInfo(buildInfo, options.out, cwd);
+
+  console.log(`Created ${outPath}`);
+  console.log(`buildId: ${buildInfo.buildId}`);
+
+  return 0;
+}
+
+function isDirectCliInvocation(argvPath, currentFilePath) {
+  if (!argvPath) {
+    return false;
+  }
+
+  try {
+    return realpathSync(argvPath) === currentFilePath;
+  } catch {
+    return resolve(argvPath) === currentFilePath;
+  }
+}
+
+const currentFilePath = fileURLToPath(import.meta.url);
+
+if (isDirectCliInvocation(process.argv[1], currentFilePath)) {
+  try {
+    process.exitCode = run();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}
+
+export {
+  createBuildId,
+  createBuildInfo,
+  parseArgs,
+  readGitInfo,
+  run,
+  writeBuildInfo,
+  isDirectCliInvocation
+};

package/dist/components/BuildReloadWatcher.d.ts

@@ -0,0 +1,3 @@
+import type { BuildReloadWatcherProps } from "../types";
+export declare function BuildReloadWatcher({ promptMessage, refreshButtonLabel, dismissButtonLabel, promptPosition, showDismissButton, reloadOnChunkError, ...options }: BuildReloadWatcherProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=BuildReloadWatcher.d.ts.map

package/dist/components/BuildReloadWatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BuildReloadWatcher.d.ts","sourceRoot":"","sources":["../../src/components/BuildReloadWatcher.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAoDxD,wBAAgB,kBAAkB,CAAC,EACjC,aAAgE,EAChE,kBAA8B,EAC9B,kBAA8B,EAC9B,cAAyB,EACzB,iBAAwB,EACxB,kBAAyB,EACzB,GAAG,OAAO,EACX,EAAE,uBAAuB,kDA6CzB"}

package/dist/hooks/useBuildReload.d.ts

@@ -0,0 +1,3 @@
+import type { UseBuildReloadOptions, UseBuildReloadResult } from "../types";
+export declare function useBuildReload(options?: UseBuildReloadOptions): UseBuildReloadResult;
+//# sourceMappingURL=useBuildReload.d.ts.map

package/dist/hooks/useBuildReload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBuildReload.d.ts","sourceRoot":"","sources":["../../src/hooks/useBuildReload.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAIV,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,UAAU,CAAC;AAMlB,wBAAgB,cAAc,CAC5B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAiJtB"}

package/dist/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("react"),t=require("react/jsx-runtime");var n=[/loading chunk \d* failed/i,/chunkloaderror/i,/failed to fetch dynamically imported module/i,/importing a module script failed/i,/error loading dynamically imported module/i,/unable to preload css/i],r=`react-build-reload:chunk-error-reloaded`;function i(e){if(typeof e==`string`)return e;if(e instanceof Error)return`${e.name} ${e.message}`;if(typeof e==`object`&&e){let t=e;return[t.message,t.reason,t.type].filter(Boolean).map(String).join(` `)}return``}function a(e){let t=i(e);return n.some(e=>e.test(t))}function o(e,t){if(typeof window>`u`)return()=>void 0;let n=n=>{if(!a(n))return;let o=n instanceof Error?n:Error(i(n)||`Chunk loading failed.`);t?.(o),sessionStorage.getItem(r)!==`true`&&(sessionStorage.setItem(r,`true`),e())},o=e=>{n(e.error??e.message)},s=e=>{n(e.reason)};return window.addEventListener(`error`,o),window.addEventListener(`unhandledrejection`,s),()=>{window.removeEventListener(`error`,o),window.removeEventListener(`unhandledrejection`,s)}}var s=class extends Error{constructor(e){super(e),this.name=`BuildReloadError`}},c=`/build-version.json`;function l(e,t=Date.now()){let n=/^[a-z][a-z\d+\-.]*:/i.test(e),r=typeof window>`u`?`http://localhost`:window.location.href,i=new URL(e,r);return i.searchParams.set(`t`,String(t)),n?i.toString():`${i.pathname}${i.search}${i.hash}`}function u(e){return typeof e==`object`&&!!e&&`buildId`in e&&typeof e.buildId==`string`&&e.buildId.trim().length>0}async function d(e=c,t){let n;try{n=await fetch(l(e),{cache:`no-store`,signal:t})}catch(e){throw e instanceof Error?e:new s(`Failed to fetch build information.`)}if(!n.ok)throw new s(`Failed to fetch build information: ${n.status} ${n.statusText}`.trim());let r;try{r=await n.json()}catch{throw new s(`Build information response is not valid JSON.`)}if(!u(r))throw new s(`Build information must include a non-empty buildId.`);return r}function f(e,t){return!e||!t?!1:e!==t}function p(){typeof window>`u`||window.location.reload()}var m=6e4,h=`prompt`,g=0;function _(t={}){let{versionUrl:n=c,currentBuildId:r,checkInterval:i=m,reloadMode:a=h,reloadDelay:o=g,enabled:s=!0,onNewBuild:l,onError:u}=t,[_,v]=(0,e.useState)(r??null),[y,b]=(0,e.useState)(null),[x,S]=(0,e.useState)(!1),[C,w]=(0,e.useState)(null),T=(0,e.useRef)(r??null),E=(0,e.useRef)(null),D=(0,e.useRef)(null),O=(0,e.useRef)(null),k=(0,e.useRef)(l),A=(0,e.useRef)(u);(0,e.useEffect)(()=>{k.current=l},[l]),(0,e.useEffect)(()=>{A.current=u},[u]),(0,e.useEffect)(()=>{r!==void 0&&(T.current=r,v(r))},[r]);let j=(0,e.useCallback)(()=>{p()},[]),M=(0,e.useCallback)(e=>{E.current!==e.latestBuildId&&(E.current=e.latestBuildId,S(!0),k.current?.(e),a===`auto`&&(D.current=setTimeout(j,Math.max(0,o))))},[j,o,a]),N=(0,e.useCallback)(async()=>{if(!s)return;O.current?.abort();let e=new AbortController;O.current=e;try{let t=await d(n,e.signal);b(t),w(null);let r=T.current;if(!r){T.current=t.buildId,v(t.buildId);return}f(r,t.buildId)&&M({currentBuildId:r,latestBuildId:t.buildId,latestBuildInfo:t})}catch(e){if(e instanceof DOMException&&e.name===`AbortError`)return;let t=e instanceof Error?e:Error(`Build reload check failed.`);w(t),A.current?.(t)}},[s,M,n]);(0,e.useEffect)(()=>{if(!s)return;N();let e=window.setInterval(()=>{N()},Math.max(1e3,i));return()=>{window.clearInterval(e),O.current?.abort(),D.current&&clearTimeout(D.current)}},[i,N,s]);let P=(0,e.useCallback)(()=>{S(!1)},[]);return{isNewBuildAvailable:x,currentBuildId:_,latestBuildId:y?.buildId??null,latestBuildInfo:y,error:C,reloadApp:j,checkNow:N,dismissPrompt:P}}var v={position:`fixed`,left:`16px`,right:`16px`,zIndex:2147483647,display:`flex`,alignItems:`center`,justifyContent:`space-between`,gap:`12px`,padding:`12px 14px`,borderRadius:`8px`,background:`#111827`,color:`#ffffff`,boxShadow:`0 12px 28px rgba(17, 24, 39, 0.24)`,fontFamily:`Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif`,fontSize:`14px`,lineHeight:1.4},y={display:`flex`,alignItems:`center`,gap:`8px`,flexShrink:0},b={border:0,borderRadius:`6px`,padding:`7px 10px`,cursor:`pointer`,font:`inherit`,fontWeight:600},x={...b,background:`#ffffff`,color:`#111827`},S={...b,background:`transparent`,color:`#d1d5db`};function C({promptMessage:n=`A new version is available. Refresh to update.`,refreshButtonLabel:r=`Refresh`,dismissButtonLabel:i=`Dismiss`,promptPosition:a=`bottom`,showDismissButton:s=!0,reloadOnChunkError:c=!0,...l}){let{isNewBuildAvailable:u,reloadApp:d,dismissPrompt:f}=_(l);if((0,e.useEffect)(()=>{if(c)return o(d,l.onError)},[d,c,l.onError]),l.reloadMode===`manual`||!u)return null;let p=a===`top`?{top:`16px`}:{bottom:`16px`};return(0,t.jsxs)(`div`,{role:`status`,"aria-live":`polite`,style:{...v,...p},children:[(0,t.jsx)(`span`,{children:n}),(0,t.jsxs)(`div`,{style:y,children:[s?(0,t.jsx)(`button`,{type:`button`,style:S,onClick:f,children:i}):null,(0,t.jsx)(`button`,{type:`button`,style:x,onClick:d,children:r})]})]})}exports.BuildReloadWatcher=C,exports.DEFAULT_VERSION_URL=c,exports.createCacheSafeUrl=l,exports.fetchBuildInfo=d,exports.hasBuildChanged=f,exports.installChunkErrorReload=o,exports.isChunkLoadError=a,exports.useBuildReload=_;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { BuildReloadWatcher } from "./components/BuildReloadWatcher";
+export { useBuildReload } from "./hooks/useBuildReload";
+export { createCacheSafeUrl, fetchBuildInfo, DEFAULT_VERSION_URL } from "./utils/fetchBuildInfo";
+export { hasBuildChanged } from "./utils/compareBuildId";
+export { isChunkLoadError, installChunkErrorReload } from "./utils/chunkErrors";
+export type { BuildInfo, BuildReloadConfig, BuildReloadWatcherProps, NewBuildPayload, PromptPosition, ReloadMode, UseBuildReloadOptions, UseBuildReloadResult } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAChF,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,uBAAuB,EACvB,eAAe,EACf,cAAc,EACd,UAAU,EACV,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,238 @@
+import { useCallback as e, useEffect as t, useRef as n, useState as r } from "react";
+import { jsx as i, jsxs as a } from "react/jsx-runtime";
+//#region src/utils/chunkErrors.ts
+var o = [
+	/loading chunk \d* failed/i,
+	/chunkloaderror/i,
+	/failed to fetch dynamically imported module/i,
+	/importing a module script failed/i,
+	/error loading dynamically imported module/i,
+	/unable to preload css/i
+], s = "react-build-reload:chunk-error-reloaded";
+function c(e) {
+	if (typeof e == "string") return e;
+	if (e instanceof Error) return `${e.name} ${e.message}`;
+	if (typeof e == "object" && e) {
+		let t = e;
+		return [
+			t.message,
+			t.reason,
+			t.type
+		].filter(Boolean).map(String).join(" ");
+	}
+	return "";
+}
+function l(e) {
+	let t = c(e);
+	return o.some((e) => e.test(t));
+}
+function u(e, t) {
+	if (typeof window > "u") return () => void 0;
+	let n = (n) => {
+		if (!l(n)) return;
+		let r = n instanceof Error ? n : Error(c(n) || "Chunk loading failed.");
+		t?.(r), sessionStorage.getItem(s) !== "true" && (sessionStorage.setItem(s, "true"), e());
+	}, r = (e) => {
+		n(e.error ?? e.message);
+	}, i = (e) => {
+		n(e.reason);
+	};
+	return window.addEventListener("error", r), window.addEventListener("unhandledrejection", i), () => {
+		window.removeEventListener("error", r), window.removeEventListener("unhandledrejection", i);
+	};
+}
+//#endregion
+//#region src/types/index.ts
+var d = class extends Error {
+	constructor(e) {
+		super(e), this.name = "BuildReloadError";
+	}
+}, f = "/build-version.json";
+function p(e, t = Date.now()) {
+	let n = /^[a-z][a-z\d+\-.]*:/i.test(e), r = typeof window > "u" ? "http://localhost" : window.location.href, i = new URL(e, r);
+	return i.searchParams.set("t", String(t)), n ? i.toString() : `${i.pathname}${i.search}${i.hash}`;
+}
+function m(e) {
+	return typeof e == "object" && !!e && "buildId" in e && typeof e.buildId == "string" && e.buildId.trim().length > 0;
+}
+async function h(e = f, t) {
+	let n;
+	try {
+		n = await fetch(p(e), {
+			cache: "no-store",
+			signal: t
+		});
+	} catch (e) {
+		throw e instanceof Error ? e : new d("Failed to fetch build information.");
+	}
+	if (!n.ok) throw new d(`Failed to fetch build information: ${n.status} ${n.statusText}`.trim());
+	let r;
+	try {
+		r = await n.json();
+	} catch {
+		throw new d("Build information response is not valid JSON.");
+	}
+	if (!m(r)) throw new d("Build information must include a non-empty buildId.");
+	return r;
+}
+//#endregion
+//#region src/utils/compareBuildId.ts
+function g(e, t) {
+	return !e || !t ? !1 : e !== t;
+}
+//#endregion
+//#region src/utils/reloadPage.ts
+function _() {
+	typeof window > "u" || window.location.reload();
+}
+//#endregion
+//#region src/hooks/useBuildReload.ts
+var v = 6e4, y = "prompt", b = 0;
+function x(i = {}) {
+	let { versionUrl: a = f, currentBuildId: o, checkInterval: s = v, reloadMode: c = y, reloadDelay: l = b, enabled: u = !0, onNewBuild: d, onError: p } = i, [m, x] = r(o ?? null), [S, C] = r(null), [w, T] = r(!1), [E, D] = r(null), O = n(o ?? null), k = n(null), A = n(null), j = n(null), M = n(d), N = n(p);
+	t(() => {
+		M.current = d;
+	}, [d]), t(() => {
+		N.current = p;
+	}, [p]), t(() => {
+		o !== void 0 && (O.current = o, x(o));
+	}, [o]);
+	let P = e(() => {
+		_();
+	}, []), F = e((e) => {
+		k.current !== e.latestBuildId && (k.current = e.latestBuildId, T(!0), M.current?.(e), c === "auto" && (A.current = setTimeout(P, Math.max(0, l))));
+	}, [
+		P,
+		l,
+		c
+	]), I = e(async () => {
+		if (!u) return;
+		j.current?.abort();
+		let e = new AbortController();
+		j.current = e;
+		try {
+			let t = await h(a, e.signal);
+			C(t), D(null);
+			let n = O.current;
+			if (!n) {
+				O.current = t.buildId, x(t.buildId);
+				return;
+			}
+			g(n, t.buildId) && F({
+				currentBuildId: n,
+				latestBuildId: t.buildId,
+				latestBuildInfo: t
+			});
+		} catch (e) {
+			if (e instanceof DOMException && e.name === "AbortError") return;
+			let t = e instanceof Error ? e : /* @__PURE__ */ Error("Build reload check failed.");
+			D(t), N.current?.(t);
+		}
+	}, [
+		u,
+		F,
+		a
+	]);
+	t(() => {
+		if (!u) return;
+		I();
+		let e = window.setInterval(() => {
+			I();
+		}, Math.max(1e3, s));
+		return () => {
+			window.clearInterval(e), j.current?.abort(), A.current && clearTimeout(A.current);
+		};
+	}, [
+		s,
+		I,
+		u
+	]);
+	let L = e(() => {
+		T(!1);
+	}, []);
+	return {
+		isNewBuildAvailable: w,
+		currentBuildId: m,
+		latestBuildId: S?.buildId ?? null,
+		latestBuildInfo: S,
+		error: E,
+		reloadApp: P,
+		checkNow: I,
+		dismissPrompt: L
+	};
+}
+//#endregion
+//#region src/components/BuildReloadWatcher.tsx
+var S = {
+	position: "fixed",
+	left: "16px",
+	right: "16px",
+	zIndex: 2147483647,
+	display: "flex",
+	alignItems: "center",
+	justifyContent: "space-between",
+	gap: "12px",
+	padding: "12px 14px",
+	borderRadius: "8px",
+	background: "#111827",
+	color: "#ffffff",
+	boxShadow: "0 12px 28px rgba(17, 24, 39, 0.24)",
+	fontFamily: "Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif",
+	fontSize: "14px",
+	lineHeight: 1.4
+}, C = {
+	display: "flex",
+	alignItems: "center",
+	gap: "8px",
+	flexShrink: 0
+}, w = {
+	border: 0,
+	borderRadius: "6px",
+	padding: "7px 10px",
+	cursor: "pointer",
+	font: "inherit",
+	fontWeight: 600
+}, T = {
+	...w,
+	background: "#ffffff",
+	color: "#111827"
+}, E = {
+	...w,
+	background: "transparent",
+	color: "#d1d5db"
+};
+function D({ promptMessage: e = "A new version is available. Refresh to update.", refreshButtonLabel: n = "Refresh", dismissButtonLabel: r = "Dismiss", promptPosition: o = "bottom", showDismissButton: s = !0, reloadOnChunkError: c = !0, ...l }) {
+	let { isNewBuildAvailable: d, reloadApp: f, dismissPrompt: p } = x(l);
+	if (t(() => {
+		if (c) return u(f, l.onError);
+	}, [
+		f,
+		c,
+		l.onError
+	]), l.reloadMode === "manual" || !d) return null;
+	let m = o === "top" ? { top: "16px" } : { bottom: "16px" };
+	return /* @__PURE__ */ a("div", {
+		role: "status",
+		"aria-live": "polite",
+		style: {
+			...S,
+			...m
+		},
+		children: [/* @__PURE__ */ i("span", { children: e }), /* @__PURE__ */ a("div", {
+			style: C,
+			children: [s ? /* @__PURE__ */ i("button", {
+				type: "button",
+				style: E,
+				onClick: p,
+				children: r
+			}) : null, /* @__PURE__ */ i("button", {
+				type: "button",
+				style: T,
+				onClick: f,
+				children: n
+			})]
+		})]
+	});
+}
+//#endregion
+export { D as BuildReloadWatcher, f as DEFAULT_VERSION_URL, p as createCacheSafeUrl, h as fetchBuildInfo, g as hasBuildChanged, u as installChunkErrorReload, l as isChunkLoadError, x as useBuildReload };

package/dist/types/index.d.ts

@@ -0,0 +1,49 @@
+import type { ReactNode } from "react";
+export type ReloadMode = "prompt" | "auto" | "manual";
+export type PromptPosition = "top" | "bottom";
+export interface BuildInfo {
+    buildId: string;
+    version?: string;
+    builtAt?: string;
+    environment?: string;
+    [key: string]: unknown;
+}
+export interface NewBuildPayload {
+    currentBuildId: string;
+    latestBuildId: string;
+    latestBuildInfo: BuildInfo;
+}
+export interface BuildReloadConfig {
+    versionUrl?: string;
+    currentBuildId?: string;
+    checkInterval?: number;
+    reloadMode?: ReloadMode;
+    reloadDelay?: number;
+    enabled?: boolean;
+    reloadOnChunkError?: boolean;
+    onNewBuild?: (payload: NewBuildPayload) => void;
+    onError?: (error: Error) => void;
+}
+export interface UseBuildReloadOptions extends BuildReloadConfig {
+}
+export interface UseBuildReloadResult {
+    isNewBuildAvailable: boolean;
+    currentBuildId: string | null;
+    latestBuildId: string | null;
+    latestBuildInfo: BuildInfo | null;
+    error: Error | null;
+    reloadApp: () => void;
+    checkNow: () => Promise<void>;
+    dismissPrompt: () => void;
+}
+export interface BuildReloadWatcherProps extends BuildReloadConfig {
+    promptMessage?: ReactNode;
+    refreshButtonLabel?: string;
+    dismissButtonLabel?: string;
+    promptPosition?: PromptPosition;
+    showDismissButton?: boolean;
+}
+export declare class BuildReloadError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEtD,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,QAAQ,CAAC;AAE9C,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;IAChD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;CAAG;AAEnE,MAAM,WAAW,oBAAoB;IACnC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,EAAE,SAAS,GAAG,IAAI,CAAC;IAClC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,aAAa,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,uBAAwB,SAAQ,iBAAiB;IAChE,aAAa,CAAC,EAAE,SAAS,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B"}

package/dist/utils/chunkErrors.d.ts

@@ -0,0 +1,4 @@
+export declare function isChunkLoadError(error: unknown): boolean;
+export declare function clearChunkReloadMarker(): void;
+export declare function installChunkErrorReload(reloadApp: () => void, onError?: (error: Error) => void): () => void;
+//# sourceMappingURL=chunkErrors.d.ts.map

package/dist/utils/chunkErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunkErrors.d.ts","sourceRoot":"","sources":["../../src/utils/chunkErrors.ts"],"names":[],"mappings":"AA+BA,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGxD;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAM7C;AAED,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,IAAI,EACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAC/B,MAAM,IAAI,CAyCZ"}

package/dist/utils/compareBuildId.d.ts

@@ -0,0 +1,2 @@
+export declare function hasBuildChanged(currentBuildId: string | null | undefined, latestBuildId: string | null | undefined): boolean;
+//# sourceMappingURL=compareBuildId.d.ts.map

package/dist/utils/compareBuildId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compareBuildId.d.ts","sourceRoot":"","sources":["../../src/utils/compareBuildId.ts"],"names":[],"mappings":"AAAA,wBAAgB,eAAe,CAC7B,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACzC,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACvC,OAAO,CAMT"}

package/dist/utils/fetchBuildInfo.d.ts

@@ -0,0 +1,6 @@
+import { type BuildInfo } from "../types";
+export declare const DEFAULT_VERSION_URL = "/build-version.json";
+export declare const CACHE_BUST_PARAM = "t";
+export declare function createCacheSafeUrl(versionUrl: string, now?: number): string;
+export declare function fetchBuildInfo(versionUrl?: string, signal?: AbortSignal): Promise<BuildInfo>;
+//# sourceMappingURL=fetchBuildInfo.d.ts.map

package/dist/utils/fetchBuildInfo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchBuildInfo.d.ts","sourceRoot":"","sources":["../../src/utils/fetchBuildInfo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAE5D,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AACzD,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,MAAM,CAa/E;AAYD,wBAAsB,cAAc,CAClC,UAAU,SAAsB,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,SAAS,CAAC,CAmCpB"}

package/dist/utils/reloadPage.d.ts

@@ -0,0 +1,2 @@
+export declare function reloadPage(): void;
+//# sourceMappingURL=reloadPage.d.ts.map

package/dist/utils/reloadPage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reloadPage.d.ts","sourceRoot":"","sources":["../../src/utils/reloadPage.ts"],"names":[],"mappings":"AAAA,wBAAgB,UAAU,IAAI,IAAI,CAMjC"}

package/docs/api-reference.md

@@ -0,0 +1,87 @@
+# API Reference
+
+## `BuildReloadWatcher`
+
+```tsx
+<BuildReloadWatcher />
+```
+
+Component that starts polling, handles chunk load errors, and renders the default prompt UI when needed.
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `versionUrl` | `string` | `"/build-version.json"` | URL that returns the latest build info. |
+| `currentBuildId` | `string` | first fetched `buildId` | Current running app build ID. |
+| `checkInterval` | `number` | `60000` | Poll interval in milliseconds. Minimum runtime interval is clamped to 1000 ms. |
+| `reloadMode` | `"prompt" \| "auto" \| "manual"` | `"prompt"` | What happens when a new build is detected. |
+| `reloadDelay` | `number` | `0` | Delay before automatic reload in `auto` mode. |
+| `enabled` | `boolean` | `true` | Enables or disables polling. |
+| `reloadOnChunkError` | `boolean` | `true` | Reload once when common dynamic import/chunk failures occur. |
+| `onNewBuild` | `(payload) => void` | `undefined` | Called once when a new build is detected. |
+| `onError` | `(error) => void` | `undefined` | Called when fetching or parsing build info fails. |
+| `promptMessage` | `ReactNode` | default message | Prompt text or node. |
+| `refreshButtonLabel` | `string` | `"Refresh"` | Refresh button label. |
+| `dismissButtonLabel` | `string` | `"Dismiss"` | Dismiss button label. |
+| `promptPosition` | `"top" \| "bottom"` | `"bottom"` | Default prompt position. |
+| `showDismissButton` | `boolean` | `true` | Whether the prompt includes a dismiss button. |
+
+## `useBuildReload`
+
+```tsx
+const state = useBuildReload(options);
+```
+
+Hook for custom UI or manual integration.
+
+### Return Value
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `isNewBuildAvailable` | `boolean` | True after a different latest `buildId` is detected. |
+| `currentBuildId` | `string \| null` | Running app build ID. |
+| `latestBuildId` | `string \| null` | Latest fetched build ID. |
+| `latestBuildInfo` | `BuildInfo \| null` | Full latest response object. |
+| `error` | `Error \| null` | Last non-abort error from version checking. |
+| `reloadApp` | `() => void` | Reloads the current page. |
+| `checkNow` | `() => Promise<void>` | Runs an immediate version check. |
+| `dismissPrompt` | `() => void` | Clears the prompt state locally. |
+
+## Types
+
+```ts
+type ReloadMode = "prompt" | "auto" | "manual";
+
+interface BuildInfo {
+  buildId: string;
+  version?: string;
+  builtAt?: string;
+  environment?: string;
+  [key: string]: unknown;
+}
+
+interface NewBuildPayload {
+  currentBuildId: string;
+  latestBuildId: string;
+  latestBuildInfo: BuildInfo;
+}
+```
+
+## CLI
+
+```bash
+react-build-reload generate [options]
+```
+
+Creates a JSON build metadata file for the runtime watcher.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--out <path>` | `public/build-version.json` | Output file path. Parent folders are created automatically. |
+| `--build-id <id>` | env/git/timestamp | Build ID to write. |
+| `--version <version>` | app `package.json` version or `0.0.0` | Version value to write. |
+| `--environment <name>` | `NODE_ENV` or `production` | Environment value to write. |
+| `--no-git` | disabled | Skips git metadata lookup. |
+
+Generated files include `buildId`, `version`, `builtAt`, `environment`, and `name` when available. Git metadata is included when git is available and `--no-git` is not used.

package/docs/getting-started.md

@@ -0,0 +1,97 @@
+# Getting Started
+
+`react-build-reload` watches a build version endpoint and detects when the running app is older than the deployed app.
+
+## 1. Install
+
+```bash
+npm install react-build-reload
+```
+
+## 2. Generate a Version File
+
+Run this in your app before building:
+
+```bash
+npx react-build-reload generate
+```
+
+This creates:
+
+```txt
+public/build-version.json
+```
+
+Example output:
+
+```json
+{
+  "buildId": "abc123-20260530123000",
+  "version": "1.0.0",
+  "builtAt": "2026-05-30T12:30:00.000Z",
+  "environment": "production",
+  "name": "my-app"
+}
+```
+
+The default URL is:
+
+```txt
+/build-version.json
+```
+
+The generator uses an explicit build ID, common CI environment variables, git metadata, or a timestamp fallback. The runtime library only requires `buildId`.
+
+Add it to your app build scripts:
+
+```json
+{
+  "scripts": {
+    "prebuild": "react-build-reload generate",
+    "build": "vite build"
+  }
+}
+```
+
+## 3. Add the Watcher
+
+```tsx
+import { BuildReloadWatcher } from "react-build-reload";
+
+function App() {
+  return (
+    <>
+      <BuildReloadWatcher />
+      <MainApp />
+    </>
+  );
+}
+```
+
+By default, the watcher checks every 60 seconds and shows a refresh prompt when a new build is detected.
+
+## 4. Use Your Own Endpoint
+
+```tsx
+<BuildReloadWatcher versionUrl="/api/version" />
+```
+
+The endpoint should return JSON with a non-empty `buildId`.
+
+## 5. Disable in Development
+
+```tsx
+<BuildReloadWatcher enabled={import.meta.env.PROD} />
+```
+
+This keeps local development from repeatedly checking a file that may not exist.
+
+## 6. Generator Options
+
+```bash
+react-build-reload generate --out public/build-version.json
+react-build-reload generate --build-id "$GITHUB_SHA"
+react-build-reload generate --environment staging
+react-build-reload generate --version 2.0.0
+react-build-reload generate --no-git
+```

package/docs/roadmap.md

@@ -0,0 +1,26 @@
+# Roadmap
+
+These items are intentionally outside the MVP.
+
+## Future Features
+
+- Multi-tab synchronization with `BroadcastChannel` or storage events.
+- Custom prompt render prop or component slot.
+- Toast notification integrations.
+- Next.js-specific guidance and compatibility helpers.
+- Service worker update coordination.
+- Vite or Webpack plugin wrappers around the existing generator.
+- Deployment metadata display.
+- Environment-specific behavior.
+- Pause checks while users are typing.
+- Check immediately when a tab becomes active again.
+
+## Non-MVP Boundaries
+
+The MVP remains focused on React runtime behavior:
+
+- Poll a version URL.
+- Compare build IDs.
+- Prompt, reload, or call a callback.
+- Recover once from chunk load failures.
+- Avoid breaking the app when version checks fail.

package/docs/usage-examples.md

@@ -0,0 +1,85 @@
+# Usage Examples
+
+## Generate Before Vite Build
+
+```json
+{
+  "scripts": {
+    "prebuild": "react-build-reload generate",
+    "build": "vite build"
+  }
+}
+```
+
+Vite copies `public/build-version.json` to `/build-version.json` during build.
+
+## Generate with CI Build ID
+
+```bash
+react-build-reload generate --build-id "$GITHUB_SHA" --environment production
+```
+
+## Prompt Mode
+
+```tsx
+<BuildReloadWatcher reloadMode="prompt" />
+```
+
+Shows a small refresh prompt when a new build is detected. This is the default and safest mode for user-facing apps.
+
+## Auto Reload
+
+```tsx
+<BuildReloadWatcher reloadMode="auto" reloadDelay={3000} />
+```
+
+Reloads after a new build is detected. Use this for dashboards, internal tools, or monitoring screens where showing the latest version is more important than preserving unsaved input.
+
+## Manual Callback
+
+```tsx
+<BuildReloadWatcher
+  reloadMode="manual"
+  onNewBuild={({ latestBuildId }) => {
+    showToast(`New build available: ${latestBuildId}`);
+  }}
+/>
+```
+
+Use this when the application already has its own modal, toast, or unsaved-work flow.
+
+## Custom Version URL
+
+```tsx
+<BuildReloadWatcher versionUrl="/api/version" />
+```
+
+The endpoint must return JSON with `buildId`.
+
+## Disabled in Development
+
+```tsx
+<BuildReloadWatcher enabled={import.meta.env.PROD} />
+```
+
+This avoids noisy local errors when `/build-version.json` is not available during development.
+
+## Hook with Custom UI
+
+```tsx
+function ReloadToast() {
+  const { isNewBuildAvailable, reloadApp, dismissPrompt } = useBuildReload({
+    reloadMode: "manual"
+  });
+
+  if (!isNewBuildAvailable) return null;
+
+  return (
+    <div>
+      <span>A new version is available.</span>
+      <button onClick={dismissPrompt}>Later</button>
+      <button onClick={reloadApp}>Refresh</button>
+    </div>
+  );
+}
+```

package/docs/version-file.md

@@ -0,0 +1,63 @@
+# Version File
+
+The library needs a URL that returns the latest deployed build ID. You can create this file with the included CLI.
+
+## Generate the File
+
+```bash
+react-build-reload generate
+```
+
+Default output:
+
+```txt
+public/build-version.json
+```
+
+Recommended app setup:
+
+```json
+{
+  "scripts": {
+    "prebuild": "react-build-reload generate",
+    "build": "vite build"
+  }
+}
+```
+
+## Required Shape
+
+```json
+{
+  "buildId": "abc123"
+}
+```
+
+`buildId` must be a non-empty string. It should change on every frontend deployment.
+
+## Optional Metadata
+
+```json
+{
+  "buildId": "abc123",
+  "version": "1.0.0",
+  "builtAt": "2026-05-30T12:30:00Z",
+  "environment": "production"
+}
+```
+
+Optional fields are preserved in `latestBuildInfo` and passed to `onNewBuild`.
+
+## Cache Safety
+
+Every version check adds a timestamp query param:
+
+```txt
+/build-version.json?t=123456789
+```
+
+The request also uses `cache: "no-store"`. This reduces the chance of comparing against stale browser-cached metadata.
+
+## Deployment Responsibility
+
+The consuming app owns when the file is generated and deployed. The included CLI writes the file, but your app build or CI pipeline must run it before publishing assets.

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "react-build-reload",
+  "version": "0.1.1",
+  "description": "React library for detecting new frontend builds and reloading safely.",
+  "type": "module",
+  "author": {
+    "name": "Satyam Shah",
+    "url": "https://github.com/satyam-shah-gt"
+  },
+  "homepage": "https://react-refresh-website.satyamshah.workers.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/satyam-shah-gt/react-build-reload"
+  },
+  "bugs": {
+    "url": "https://github.com/satyam-shah-gt/react-build-reload/issues"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "react-build-reload": "./bin/react-build-reload.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "docs/getting-started.md",
+    "docs/api-reference.md",
+    "docs/version-file.md",
+    "docs/usage-examples.md",
+    "docs/roadmap.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "generate:version": "node ./bin/react-build-reload.js generate",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "react",
+    "reload",
+    "deployment",
+    "build-version",
+    "frontend"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^24.12.3",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "jsdom": "^26.1.0",
+    "typescript": "~6.0.2",
+    "vite": "^8.0.12",
+    "vitest": "^4.1.7"
+  }
+}