;
+ dismissUpdate: () => void;
};
type ClearBrowserCacheProps = {
@@ -45,8 +89,15 @@ type ClearBrowserCacheProps = {
type State = ClearBrowserCacheBoundaryState & {
caughtError: { error: unknown; rethrow: boolean } | null;
+ dismissedVersion: string | null;
};
+type CheckResult = 'reloading' | 'outdated' | 'current' | 'failed';
+
+// `guarded` reloads only if `canReload` agrees; `unattended` follows
+// `onUpdate` and `reloadWhenHidden`.
+type ReloadPolicy = 'always' | 'never' | 'guarded' | 'unattended';
+
const unknownVersion = 'latest';
const localStorageAdapter: ClearBrowserCacheStorage = {
@@ -70,6 +121,25 @@ function isUrlLike(filename: string) {
return /^(\/|\.{1,2}\/|[a-z][a-z\d+.-]*:)/i.test(filename);
}
+const componentTypes = new Set([
+ Symbol.for('react.memo'),
+ Symbol.for('react.forward_ref'),
+ Symbol.for('react.lazy')
+]);
+
+// A ReactNode can be an object too (an element, a portal), so a component is
+// told apart by being a function or one of React's component wrappers.
+function isComponentType(
+ value: React.ReactNode | React.ComponentType
+): value is React.ComponentType
{
+ return (
+ typeof value === 'function' ||
+ (typeof value === 'object' &&
+ value !== null &&
+ componentTypes.has((value as { $$typeof?: symbol }).$$typeof!))
+ );
+}
+
function readStoredVersion(storage: ClearBrowserCacheStorage, key: string) {
try {
return { version: storage.get(key), disabled: false };
@@ -84,27 +154,23 @@ export class ClearBrowserCacheBoundary extends React.Component<
> {
// Version whose assets the browser currently holds; null before the first
// successful check on this device.
- appVersion: string | null;
+ appVersion: string | null = null;
checkInterval: ReturnType | null = null;
+ lastCheckAt = 0;
+ storageRead = false;
+ storageEnabled = true;
unmounted = false;
- constructor(props: ClearBrowserCacheBoundaryProps) {
- super(props);
-
- const { version, disabled } = readStoredVersion(
- this.storage,
- this.storageKey
- );
-
- this.appVersion = version;
- this.state = {
- loading: !disabled,
- latestVersion: version ?? unknownVersion,
- disabled,
- isLatestVersion: true,
- caughtError: null
- };
- }
+ // Storage is read after mount, not here: the server has none, and the first
+ // client render has to match the server's HTML to hydrate.
+ state: State = {
+ loading: true,
+ latestVersion: unknownVersion,
+ disabled: false,
+ isLatestVersion: true,
+ caughtError: null,
+ dismissedVersion: null
+ };
static getDerivedStateFromError(error: unknown): Partial {
return { caughtError: { error, rethrow: false } };
@@ -130,16 +196,45 @@ export class ClearBrowserCacheBoundary extends React.Component<
return url.href;
}
+ // Returns whether storage works. Read once: StrictMode remounts the same
+ // instance, and a second read would undo the first check's state. The answer
+ // is kept in a field because `setState` has not landed yet when
+ // `componentDidCatch` runs in the same commit as the first mount.
+ readStorage() {
+ if (!this.storageRead) {
+ this.storageRead = true;
+
+ const { version, disabled } = readStoredVersion(
+ this.storage,
+ this.storageKey
+ );
+
+ this.appVersion = version;
+ this.storageEnabled = !disabled;
+ this.setState({
+ loading: !disabled,
+ latestVersion: version ?? unknownVersion,
+ disabled
+ });
+ }
+
+ return this.storageEnabled;
+ }
+
componentDidMount() {
// StrictMode unmounts and remounts the same instance in development.
this.unmounted = false;
- window.addEventListener('focus', this.startVersionCheck);
+ const enabled = this.readStorage();
+ window.addEventListener('focus', this.handleFocus);
window.addEventListener('blur', this.stopVersionCheck);
+ document.addEventListener('visibilitychange', this.handleVisibilityChange);
- // Nothing has been shown yet, so a stale build is reloaded on mount even
- // without `auto`.
- if (!this.state.disabled) {
- this.checkVersion({ auto: true }).then(() => {
+ // A blocking mount has shown nothing yet, so a stale build is reloaded
+ // whatever `onUpdate` says. A non-blocking one is already interactive.
+ if (enabled) {
+ const reload = (this.props.blocking ?? true) ? 'always' : 'guarded';
+
+ this.checkVersion({ reload }).then(() => {
if (!this.unmounted && document.hasFocus()) {
this.startVersionCheck();
}
@@ -150,11 +245,7 @@ export class ClearBrowserCacheBoundary extends React.Component<
}
componentDidUpdate(prevProps: ClearBrowserCacheBoundaryProps) {
- const { duration, auto } = this.props;
- const pollingChanged =
- duration !== prevProps.duration || auto !== prevProps.auto;
-
- if (pollingChanged && document.hasFocus()) {
+ if (this.props.duration !== prevProps.duration && document.hasFocus()) {
this.startVersionCheck();
}
@@ -165,8 +256,12 @@ export class ClearBrowserCacheBoundary extends React.Component<
this.unmounted = true;
this.stopVersionCheck();
- window.removeEventListener('focus', this.startVersionCheck);
+ window.removeEventListener('focus', this.handleFocus);
window.removeEventListener('blur', this.stopVersionCheck);
+ document.removeEventListener(
+ 'visibilitychange',
+ this.handleVisibilityChange
+ );
}
componentDidCatch(error: unknown, errorInfo: React.ErrorInfo) {
@@ -174,15 +269,21 @@ export class ClearBrowserCacheBoundary extends React.Component<
this.props.errorCheckers ?? []
);
- if (this.state.disabled || !isCacheError(error, errorCheckers)) {
+ // A child of a non-blocking boundary can fail before the boundary mounts.
+ if (!this.readStorage() || !isCacheError(error, errorCheckers)) {
this.rethrow(error);
return;
}
- this.checkVersion({ auto: true }).then((reloading) => {
+ const { promptOnChunkError, prompt } = this.props;
+ const ask = Boolean(promptOnChunkError) && prompt != null;
+
+ this.checkVersion({ reload: ask ? 'never' : 'always' }).then((result) => {
this.debug(error, errorInfo);
- if (!reloading) {
+ // 'outdated' only comes back with the prompt on, which now shows over
+ // the fallback and lets the user decide.
+ if (result !== 'reloading' && result !== 'outdated') {
this.rethrow(error);
}
});
@@ -194,8 +295,22 @@ export class ClearBrowserCacheBoundary extends React.Component<
}
}
+ dismissUpdate = () => {
+ const { caughtError, latestVersion } = this.state;
+
+ if (caughtError) {
+ this.rethrow(caughtError.error);
+ } else {
+ this.setState({ dismissedVersion: latestVersion });
+ }
+ };
+
debug = (error?: unknown, errorInfo?: React.ErrorInfo) => {
- const { caughtError: _caughtError, ...state } = this.state;
+ const {
+ caughtError: _caughtError,
+ dismissedVersion: _dismissedVersion,
+ ...state
+ } = this.state;
// A throwing debug callback must not break the version check that called it.
try {
@@ -205,14 +320,63 @@ export class ClearBrowserCacheBoundary extends React.Component<
}
};
+ // Polling stops while the window is in the background, so a tab left alone
+ // for hours would otherwise wait a whole `duration` after coming back.
+ handleFocus = () => {
+ const { duration } = this.props;
+
+ if (
+ !this.state.disabled &&
+ duration &&
+ Date.now() - this.lastCheckAt >= duration
+ ) {
+ this.checkVersion();
+ }
+
+ this.startVersionCheck();
+ };
+
+ handleVisibilityChange = () => {
+ const { loading, isLatestVersion, caughtError, disabled } = this.state;
+
+ if (
+ document.visibilityState !== 'hidden' ||
+ !this.props.reloadWhenHidden ||
+ disabled ||
+ loading ||
+ caughtError
+ ) {
+ return;
+ }
+
+ if (!isLatestVersion) {
+ if (this.reloadAllowed()) {
+ this.clearCacheAndReload();
+ }
+ } else if (this.props.duration) {
+ // Polling stopped on blur, so a deploy since the last poll is not known
+ // yet; checking now reloads into it while the tab is still hidden.
+ this.checkVersion();
+ }
+ };
+
+ reloadAllowed() {
+ try {
+ return this.props.canReload?.() ?? true;
+ } catch (error) {
+ this.debug(error);
+ return false;
+ }
+ }
+
startVersionCheck = () => {
- const { duration, auto = false } = this.props;
+ const { duration } = this.props;
this.stopVersionCheck();
if (!this.state.disabled && duration) {
this.checkInterval = setInterval(() => {
- this.checkVersion({ auto });
+ this.checkVersion();
}, duration);
}
};
@@ -272,8 +436,46 @@ export class ClearBrowserCacheBoundary extends React.Component<
}
}
- /** Resolves to true when a page reload was started. */
- checkVersion = async ({ auto = this.props.auto ?? false } = {}) => {
+ get updateMode(): ClearBrowserCacheUpdateMode {
+ const { onUpdate, auto, prompt } = this.props;
+
+ if (onUpdate) {
+ return onUpdate;
+ }
+
+ if (auto) {
+ return 'reload';
+ }
+
+ return prompt != null ? 'prompt' : 'flag';
+ }
+
+ // The guard is asked only once a newer build is known, so it sees the page
+ // as it is at reload time and is not called on every poll.
+ shouldReload(policy: ReloadPolicy) {
+ switch (policy) {
+ case 'always':
+ return true;
+ case 'never':
+ return false;
+ case 'guarded':
+ return this.reloadAllowed();
+ case 'unattended': {
+ const wanted =
+ this.updateMode === 'reload' ||
+ (Boolean(this.props.reloadWhenHidden) &&
+ document.visibilityState === 'hidden');
+
+ return wanted && this.reloadAllowed();
+ }
+ }
+ }
+
+ checkVersion = async ({
+ reload = 'unattended'
+ }: { reload?: ReloadPolicy } = {}): Promise => {
+ this.lastCheckAt = Date.now();
+
try {
const latestVersion = await this.fetchLatestVersion();
@@ -284,18 +486,20 @@ export class ClearBrowserCacheBoundary extends React.Component<
const isLatestVersion = latestVersion === this.appVersion;
- if (!isLatestVersion && auto) {
+ if (!isLatestVersion && this.shouldReload(reload)) {
await this.clearCacheAndReload(latestVersion);
- return true;
+ return 'reloading';
}
this.updateState({ loading: false, latestVersion, isLatestVersion });
+
+ return isLatestVersion ? 'current' : 'outdated';
} catch (error) {
this.debug(error);
this.updateState({ loading: false });
- }
- return false;
+ return 'failed';
+ }
};
updateState(patch: Partial) {
@@ -314,8 +518,44 @@ export class ClearBrowserCacheBoundary extends React.Component<
clearCacheAndReloadFromContext = () => this.clearCacheAndReload();
+ renderUpdatePrompt() {
+ const { prompt } = this.props;
+ const {
+ caughtError,
+ loading,
+ isLatestVersion,
+ latestVersion,
+ dismissedVersion
+ } = this.state;
+ const reason = caughtError ? 'error' : 'poll';
+ const dismissed = reason === 'poll' && latestVersion === dismissedVersion;
+
+ // `reload` mode lands here only when `canReload` held the reload back,
+ // so the user is asked instead.
+ const silent = reason === 'poll' && this.updateMode === 'flag';
+
+ if (prompt == null || silent || loading || isLatestVersion || dismissed) {
+ return null;
+ }
+
+ if (!isComponentType(prompt)) {
+ return prompt;
+ }
+
+ const Prompt = prompt;
+
+ return (
+
+ );
+ }
+
render() {
- const { children, fallback = null } = this.props;
+ const { children, fallback = null, blocking = true } = this.props;
const { caughtError, loading, isLatestVersion, latestVersion, disabled } =
this.state;
@@ -323,10 +563,6 @@ export class ClearBrowserCacheBoundary extends React.Component<
throw caughtError.error;
}
- if (caughtError || loading) {
- return fallback;
- }
-
return (
- {children}
+ {caughtError || (loading && blocking) ? fallback : children}
+ {this.renderUpdatePrompt()}
);
}
diff --git a/src/errorCheckers.ts b/src/errorCheckers.ts
index 0609254..446f65c 100644
--- a/src/errorCheckers.ts
+++ b/src/errorCheckers.ts
@@ -21,6 +21,9 @@ export const defaultErrorCheckers: ClearBrowserCacheErrorChecker[] = [
// webpack: numeric ids in v4, named ids in v5; mini-css-extract-plugin
// raises its CSS variant under the same name
createErrorChecker('ChunkLoadError', /Loading (?:CSS )?chunk \S+ failed/),
+ // Turbopack (Next.js): a plain Error in older releases, ChunkLoadError later
+ createErrorChecker('ChunkLoadError', /Failed to load chunk \S+/),
+ createErrorChecker('Error', /Failed to load chunk \S+/),
// older mini-css-extract-plugin releases used the generic name
createErrorChecker('Error', /Loading CSS chunk \S+ failed/),
// Vite's modulepreload helper
diff --git a/src/index.ts b/src/index.ts
index 688eebf..ad78252 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,3 +1,4 @@
export * from './ClearBrowserCacheBoundary';
export * from './errorCheckers';
export * from './lazyRetry';
+export * from './updatePrompt';
diff --git a/src/lazyRetry.ts b/src/lazyRetry.ts
index 55406e8..0f364f9 100644
--- a/src/lazyRetry.ts
+++ b/src/lazyRetry.ts
@@ -1,20 +1,21 @@
/**
- * Calls `fn` and, while it rejects, calls it again up to `retries` more times,
- * waiting `interval` ms between attempts. Rejects with the last error.
+ * Calls `fn` up to `attempts` times in all, waiting `interval` ms between
+ * attempts, until it resolves. Rejects with the last error.
*/
export function lazyRetry(
fn: () => Promise,
- retries = 2,
+ attempts = 2,
interval = 1000
): Promise {
return fn().catch((error: unknown) => {
- if (retries <= 0) {
+ // 0.x retried forever on 0; anything below 2 now means a single attempt.
+ if (attempts <= 1) {
throw error;
}
return new Promise((resolve, reject) => {
setTimeout(() => {
- lazyRetry(fn, retries - 1, interval).then(resolve, reject);
+ lazyRetry(fn, attempts - 1, interval).then(resolve, reject);
}, interval);
});
});
diff --git a/src/updatePrompt.ts b/src/updatePrompt.ts
new file mode 100644
index 0000000..8c7f0b3
--- /dev/null
+++ b/src/updatePrompt.ts
@@ -0,0 +1,18 @@
+export type UpdatePromptReason = 'poll' | 'error';
+
+export type UpdatePromptProps = {
+ latestVersion: string;
+ /**
+ * `poll`: a newer build was found while the app kept working.
+ * `error`: part of the app failed to load because of it, and the boundary
+ * shows its fallback until the user decides.
+ */
+ reason: UpdatePromptReason;
+ /** Clears Cache Storage and reloads the page. */
+ reload: () => Promise;
+ /**
+ * Hides the prompt until a newer build than `latestVersion` is found. For
+ * `reason: 'error'` the error goes on to the parent error boundary instead.
+ */
+ dismiss: () => void;
+};
diff --git a/test/ClearBrowserCacheBoundary.test.tsx b/test/ClearBrowserCacheBoundary.test.tsx
index 05f69dd..204183e 100644
--- a/test/ClearBrowserCacheBoundary.test.tsx
+++ b/test/ClearBrowserCacheBoundary.test.tsx
@@ -7,6 +7,14 @@ import {
waitFor
} from '@testing-library/react';
+import {
+ Catcher,
+ STORAGE_KEY,
+ Thrower,
+ chunkError,
+ metaResponse,
+ mockFetch
+} from './helpers';
import {
ClearBrowserCache,
ClearBrowserCacheBoundary,
@@ -15,23 +23,6 @@ import {
useClearBrowserCache
} from '../src';
-const STORAGE_KEY = 'APP_VERSION';
-
-function metaResponse(version: string) {
- return new Response(JSON.stringify({ version }), {
- headers: { 'content-type': 'application/json' }
- });
-}
-
-function mockFetch(...responses: (() => Response)[]) {
- const fetchMock = vi.fn(async (_url: string) => {
- const next = responses.length > 1 ? responses.shift()! : responses[0];
- return next();
- });
- vi.stubGlobal('fetch', fetchMock);
- return fetchMock;
-}
-
function VersionState() {
const { loading, isLatestVersion, latestVersion, disabled } =
useClearBrowserCache();
@@ -58,34 +49,6 @@ function renderBoundary(props: ClearBrowserCacheBoundaryProps = {}) {
);
}
-class Catcher extends React.Component<
- React.PropsWithChildren,
- { error: unknown }
-> {
- state = { error: null as unknown };
-
- static getDerivedStateFromError(error: unknown) {
- return { error };
- }
-
- render() {
- if (this.state.error) {
- return Caught: {String(this.state.error)}
;
- }
- return this.props.children;
- }
-}
-
-function Thrower({ error }: { error: Error }): React.ReactNode {
- throw error;
-}
-
-function chunkError() {
- const error = new Error('Loading chunk 3 failed.');
- error.name = 'ChunkLoadError';
- return error;
-}
-
describe('ClearBrowserCacheBoundary', () => {
beforeEach(() => {
// React logs every caught render error; the tests assert on the outcome.
diff --git a/test/errorCheckers.test.ts b/test/errorCheckers.test.ts
index e6ddfb7..63e38f1 100644
--- a/test/errorCheckers.test.ts
+++ b/test/errorCheckers.test.ts
@@ -13,6 +13,16 @@ function makeError(name: string, message: string) {
describe('defaultErrorCheckers', () => {
it.each([
['webpack 4 numeric chunk', 'ChunkLoadError', 'Loading chunk 3 failed.'],
+ [
+ 'Turbopack chunk',
+ 'ChunkLoadError',
+ 'Failed to load chunk /_next/static/chunks/app_reports_page.js from module 1234'
+ ],
+ [
+ 'older Turbopack chunk',
+ 'Error',
+ 'Failed to load chunk static/chunks/app_reports_page.js'
+ ],
[
'webpack 5 named chunk',
'ChunkLoadError',
diff --git a/test/helpers.tsx b/test/helpers.tsx
new file mode 100644
index 0000000..cbab198
--- /dev/null
+++ b/test/helpers.tsx
@@ -0,0 +1,46 @@
+import React from 'react';
+
+export const STORAGE_KEY = 'APP_VERSION';
+
+export function metaResponse(version: string) {
+ return new Response(JSON.stringify({ version }), {
+ headers: { 'content-type': 'application/json' }
+ });
+}
+
+export function mockFetch(...responses: (() => Response)[]) {
+ const fetchMock = vi.fn(async (_url: string) => {
+ const next = responses.length > 1 ? responses.shift()! : responses[0];
+ return next();
+ });
+ vi.stubGlobal('fetch', fetchMock);
+ return fetchMock;
+}
+
+export class Catcher extends React.Component<
+ React.PropsWithChildren,
+ { error: unknown }
+> {
+ state = { error: null as unknown };
+
+ static getDerivedStateFromError(error: unknown) {
+ return { error };
+ }
+
+ render() {
+ if (this.state.error) {
+ return Caught: {String(this.state.error)}
;
+ }
+ return this.props.children;
+ }
+}
+
+export function Thrower({ error }: { error: Error }): React.ReactNode {
+ throw error;
+}
+
+export function chunkError() {
+ const error = new Error('Loading chunk 3 failed.');
+ error.name = 'ChunkLoadError';
+ return error;
+}
diff --git a/test/hydration.test.tsx b/test/hydration.test.tsx
new file mode 100644
index 0000000..ab8a250
--- /dev/null
+++ b/test/hydration.test.tsx
@@ -0,0 +1,39 @@
+import React from 'react';
+import { act } from '@testing-library/react';
+import { hydrateRoot } from 'react-dom/client';
+import { renderToString } from 'react-dom/server';
+
+import { STORAGE_KEY, metaResponse, mockFetch } from './helpers';
+import { ClearBrowserCacheBoundary, useClearBrowserCache } from '../src';
+
+function Version() {
+ const { latestVersion } = useClearBrowserCache();
+
+ return {latestVersion}
;
+}
+
+it('hydrates server HTML without a mismatch when a version is stored', async () => {
+ window.localStorage.setItem(STORAGE_KEY, 'v1');
+ mockFetch(() => metaResponse('v1'));
+ const app = (
+
+
+
+ );
+ const container = document.createElement('div');
+ container.innerHTML = renderToString(app);
+ document.body.append(container);
+ const onRecoverableError = vi.fn();
+ const consoleError = vi.spyOn(console, 'error');
+
+ const root = await act(async () =>
+ hydrateRoot(container, app, { onRecoverableError })
+ );
+
+ expect(onRecoverableError).not.toHaveBeenCalled();
+ expect(consoleError).not.toHaveBeenCalled();
+ expect(container).toHaveTextContent('v1');
+
+ act(() => root.unmount());
+ container.remove();
+});
diff --git a/test/lazyRetry.test.ts b/test/lazyRetry.test.ts
index 1dc3792..f04c10d 100644
--- a/test/lazyRetry.test.ts
+++ b/test/lazyRetry.test.ts
@@ -32,14 +32,14 @@ describe('lazyRetry', () => {
expect(fn).toHaveBeenCalledTimes(2);
});
- it('makes `retries` extra attempts, then rejects with the last error', async () => {
+ it('makes `attempts` calls in all, then rejects with the last error', async () => {
const fn = vi
.fn()
.mockRejectedValueOnce(new Error('1'))
.mockRejectedValueOnce(new Error('2'))
.mockRejectedValueOnce(new Error('3'));
- const result = lazyRetry(fn, 2, 100);
+ const result = lazyRetry(fn, 3, 100);
const assertion = expect(result).rejects.toThrow('3');
await vi.advanceTimersByTimeAsync(200);
@@ -47,10 +47,22 @@ describe('lazyRetry', () => {
expect(fn).toHaveBeenCalledTimes(3);
});
- it('rejects at once when no retries are allowed', async () => {
+ it('makes two attempts by default, as 0.x did', async () => {
const fn = vi.fn().mockRejectedValue(new Error('gone'));
- await expect(lazyRetry(fn, 0)).rejects.toThrow('gone');
+ const assertion = expect(lazyRetry(fn, undefined, 100)).rejects.toThrow(
+ 'gone'
+ );
+
+ await vi.advanceTimersByTimeAsync(100);
+ await assertion;
+ expect(fn).toHaveBeenCalledTimes(2);
+ });
+
+ it.each([0, 1])('makes a single attempt for %i', async (attempts) => {
+ const fn = vi.fn().mockRejectedValue(new Error('gone'));
+
+ await expect(lazyRetry(fn, attempts)).rejects.toThrow('gone');
expect(fn).toHaveBeenCalledTimes(1);
});
});
diff --git a/test/serverRender.test.tsx b/test/serverRender.test.tsx
new file mode 100644
index 0000000..5a402da
--- /dev/null
+++ b/test/serverRender.test.tsx
@@ -0,0 +1,31 @@
+// @vitest-environment node
+import React from 'react';
+import { renderToString } from 'react-dom/server';
+
+import { ClearBrowserCacheBoundary } from '../src';
+
+describe('server rendering', () => {
+ it('renders the fallback without touching browser globals', () => {
+ const html = renderToString(
+ Update
}
+ >
+ App
+ 
+