You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 423801f
Browse filesBrowse the repository at this point in the historyBrowse files
feat: smoother updates with reloadWhenHidden, canReload and non-blocking mount
- Check at once when a tab gets focus back after a whole `duration`,
instead of waiting another interval on a stale build.
- `reloadWhenHidden` reloads into a newer build as soon as the tab goes to
the background, so users never see the switch.
- `canReload` is asked before every reload the user did not start (`auto`,
`reloadWhenHidden`); a throwing guard counts as a no.
- `blocking={false}` renders the app at once and checks in the background.
The demo gains controls for the new options, and the README documents them
with a reload-on-navigation recipe.
Copy file name to clipboardExpand all lines: README.md
+44-16Lines changed: 44 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,7 +21,8 @@ Users leave tabs open for days. After you deploy, those tabs still run the old b
21
21
22
22
-**Detects new builds** by polling a tiny `meta.json` that a CLI writes at build time.
23
23
-**Recovers from stale-chunk errors** — webpack and Vite chunk failures, native `import()` errors in Chrome, Firefox and Safari, and HTML served in place of a script — and passes every other error on to your own error boundary.
24
-
-**Asks or acts:** reload on its own, or show an accessible update prompt (built in, or your own component).
24
+
-**Asks or acts:** reload on its own, quietly while the tab is in the background, or show an accessible update prompt (built in, or your own component). A `canReload` guard protects unsaved work.
25
+
-**Checks when users return:** a tab that was in the background for a while checks for a new build as soon as it gets focus.
25
26
-**Clears Cache Storage** before reloading, so a service worker cannot serve the old build again.
26
27
-**`lazyRetry`** for flaky networks: retries a dynamic import before giving up.
27
28
-**Small and typed:** React 18 and 19, ESM and CommonJS, TypeScript declarations, no runtime dependencies.
**3. Deploy.** Tabs with the old build now see a prompt within a minute, or as soon as a lazy chunk fails to load.
95
96
96
-
Prefer silent reloads? Drop `updatePrompt` and set `auto`.
97
+
Prefer no prompt at all? Set `reloadWhenHidden`: the tab reloads into the new build the moment the user switches away from it. Add `canReload` to hold off while a form has unsaved changes.
98
+
99
+
```tsx
100
+
<ClearBrowserCacheBoundary
101
+
duration={60_000}
102
+
reloadWhenHidden
103
+
canReload={() =>!formIsDirty()}
104
+
>
105
+
```
97
106
98
107
## How it works
99
108
@@ -113,8 +122,9 @@ flowchart LR
113
122
I--no-->K[rethrowtoyourErrorBoundary]
114
123
```
115
124
116
-
- On mount the boundary shows `fallback` and fetches the meta file. A newer build found on mount always reloads straight away, since nothing has been shown yet.
117
-
- Polling runs every `duration` ms, only while the window has focus. When it finds a newer build it reloads if `auto` is set; otherwise it shows `updatePrompt`, or just sets `isLatestVersion` to `false` and leaves the reload to you (`clearCacheAndReload`).
125
+
- On mount the boundary shows `fallback` and fetches the meta file; with `blocking={false}` it renders the app at once and checks in the background. A newer build found on mount always reloads straight away.
126
+
- Polling runs every `duration` ms, only while the window has focus. A tab that gets focus back after a whole `duration` checks at once. When a check finds a newer build it reloads if `auto` is set; otherwise it shows `updatePrompt`, or just sets `isLatestVersion` to `false` and leaves the reload to you (`clearCacheAndReload`).
127
+
- With `reloadWhenHidden`, a tab that knows about a newer build reloads as soon as it goes to the background. `canReload` is asked before this reload and before every `auto` reload; a reload the user clicks is never blocked.
118
128
- When a child throws an error that looks like a stale build, the boundary checks the version: if a new build is out it reloads (or prompts, with `promptOnError`); otherwise the error goes on to your `ErrorBoundary`.
119
129
- The meta file is fetched with `cache:'no-store'`. A file that is missing, has no `version`, or is answered with HTML by an SPA fallback is reported to `debug` and otherwise ignored; the app still renders.
120
130
- If storage cannot be read (blocked cookies, private mode), the boundary disables itself and just renders the app.
@@ -174,18 +184,21 @@ A plain element works too (`updatePrompt={<Banner />}`); it reads `clearCacheAnd
174
184
175
185
Error boundary and context provider. Place it inside your own error boundary: it only handles stale-build errors.
|`duration`|`number`| — | Poll interval in ms. Without it the version is checked on mount and on stale-chunk errors only. |
180
-
|`auto`|`boolean`|`false`| Reload as soon as a poll finds a newer build. |
181
-
|`fallback`|`ReactNode`|`null`| Rendered while the first version check runs, e.g. a preloader. |
182
-
|`updatePrompt`| element or component | — | Shown when a newer build is found and the page is not reloaded on its own. See [Update prompt](#update-prompt). |
183
-
|`promptOnError`|`boolean`|`false`| On a stale-build error, show `updatePrompt` over `fallback` instead of reloading at once. |
184
-
|`filename`|`string`|`'meta.json'`| Meta file to fetch. A bare name is fetched from the site root; a path starting with `/`, `./` or `../`, or a full URL, is used as is. |
185
-
|`storageKey`|`string`|`'APP_VERSION'`| Key the current version is stored under. |
186
-
|`storage`|`{ get(key), set(key, value) }`|`localStorage`| Where the version is kept, e.g. [store](https://www.npmjs.com/package/store). |
187
-
|`errorCheckers`|`((error) => boolean)[]`|`[]`| Extra checks for stale-build errors, added to the defaults. See [`createErrorChecker`](#createerrorcheckername-pattern). |
188
-
|`debug`|`(params) => void`| — | Receives state changes and errors, for logging. |
| `duration` | `number` | — | Poll interval in ms. Without it the version is checked on mount and on stale-chunk errors only. |
190
+
| `auto` | `boolean` | `false` | Reload as soon as a poll finds a newer build. |
191
+
| `fallback` | `ReactNode` | `null` | Rendered while the first version check runs, e.g. a preloader. |
192
+
| `updatePrompt` | element or component | — | Shown when a newer build is found and the page is not reloaded on its own. See [Update prompt](#update-prompt). |
193
+
| `promptOnError` | `boolean` | `false` | On a stale-build error, show `updatePrompt` over `fallback` instead of reloading at once. |
194
+
| `reloadWhenHidden` | `boolean` | `false` | Reload into a newer build as soon as the tab goes to the background. |
195
+
| `canReload` | `() =>boolean` | — | Asked before reloads the user did not start (`auto`, `reloadWhenHidden`). Return `false` to keep the page. |
196
+
| `blocking` | `boolean` | `true` | Show `fallback` until the first check answers. `false` renders the app at once. |
197
+
| `filename` | `string` | `'meta.json'` | Meta file to fetch. A bare name is fetched from the site root; a path starting with `/`, `./` or `../`, or a full URL, is used as is. |
198
+
| `storageKey` | `string` | `'APP_VERSION'` | Key the current version is stored under. |
199
+
| `storage` | `{ get(key), set(key, value) }` | `localStorage` | Where the version is kept, e.g. [store](https://www.npmjs.com/package/store). |
200
+
| `errorCheckers` | `((error) =>boolean)[]` | `[]` | Extra checks for stale-build errors, added to the defaults. See [`createErrorChecker`](#createerrorcheckername-pattern). |
201
+
| `debug` | `(params) =>void` | — | Receives state changes and errors, for logging. |
189
202
190
203
### `useClearBrowserCache()` and `<ClearBrowserCache>`
191
204
@@ -266,6 +279,21 @@ Recognised out of the box: webpack `ChunkLoadError` and CSS chunk errors, Vite C
266
279
267
280
**Version from your CI instead of a random UUID.** Any JSON with a `version` string works, e.g. `echo "{\"version\":\"$GITHUB_SHA\"}">public/meta.json`.
268
281
282
+
**Reload on the next route change.** A route change replaces the screen anyway, so it is a quiet moment to switch builds:
0 commit comments