Merge pull request #7 from devmaxxx/feat/update-prompt

Release 1.0.0: update prompt, Next.js support and a live demo

Author: devmaxxx

.github/workflows/pages.yml

@@ -0,0 +1,42 @@
+name: Pages
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - run: pnpm demo:build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: example/dist-demo
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -7,6 +7,7 @@ node_modules
 
 # builds
 dist
+dist-demo
 build
 
 # misc

.prettierignore

@@ -1,4 +1,5 @@
 dist
+dist-demo
 coverage
 pnpm-lock.yaml
 playwright-report

CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 1.0.0
+
+### Breaking changes
+
+- React 18 or newer is required.
+- The package ships ESM and CommonJS builds through `exports`; deep imports into `dist/` no longer resolve.
+- The stored version is saved only when the cache is cleared, so `isLatestVersion` stays `false` until the reload.
+- `lazyRetry(fn, 0)` makes one attempt instead of retrying forever.
+- `debug` receives `error: unknown` and always receives `state`.
+
+See [Upgrading from 0.x](README.md#upgrading-from-0x).
+
+### Features
+
+- `onUpdate` (`'prompt' | 'reload' | 'flag'`) decides what a check that finds a newer build does. `auto` still works and is deprecated.
+- `prompt` asks the user to reload with your own component, which receives `UpdatePromptProps`; `promptOnChunkError` asks before reloading for a chunk error too.
+- `reloadWhenHidden` reloads into a new build when the tab goes to the background, and checks once on the way.
+- `canReload` holds back reloads the user did not start.
+- `blocking={false}` renders the app before the first check.
+- A tab that gets focus back after a whole `duration` checks at once.
+- Next.js support: the bundle is marked `'use client'`, renders on the server and hydrates without a mismatch; Turbopack chunk errors are recognised.
+- `defaultErrorCheckers` and `isCacheError` are exported.
+
+### Fixes
+
+- `lazyRetry` no longer retries forever on `0`, and keeps its result type.
+- Chunk errors from Vite, mini-css-extract-plugin, native dynamic `import()` in every major browser, and chunks answered with HTML are recognised; 0.2 knew only webpack and one SyntaxError form.

README.md

@@ -156,3 +156,75 @@ test('an SPA fallback answering meta.json with HTML does not block or loop', asy
   await expect(loads(page)).toHaveText('1');
   expect(await storedVersion(page)).toBeNull();
 });
+
+test.describe('update prompt', () => {
+  test('polling opens a modal dialog that Escape dismisses until a newer build', async ({
+    page
+  }) => {
+    const server = await deployServer(page, 'v1');
+    await page.goto('/?prompt=1&duration=200');
+    await expect(page.getByTestId('lazy')).toBeVisible();
+
+    server.deploy('v2');
+
+    const dialog = page.getByRole('dialog', {
+      name: 'A new version is available'
+    });
+    await expect(dialog).toBeVisible();
+    await expect(dialog.getByRole('button', { name: 'Reload' })).toBeFocused();
+    // Modal: the page behind is inert.
+    expect(
+      await page.evaluate(() =>
+        document.querySelector('dialog')?.matches(':modal')
+      )
+    ).toBe(true);
+
+    await page.keyboard.press('Escape');
+    await expect(dialog).toBeHidden();
+    await page.waitForTimeout(600);
+    await expect(dialog).toBeHidden();
+    await expect(loads(page)).toHaveText('1');
+
+    server.deploy('v3');
+    await expect(dialog).toBeVisible();
+  });
+
+  test('Reload in the dialog clears the cache and loads the new build', async ({
+    page
+  }) => {
+    const server = await deployServer(page, 'v1');
+    await page.goto('/?prompt=1&duration=200');
+    await expect(loads(page)).toHaveText('1');
+
+    server.deploy('v2');
+    await page.getByRole('button', { name: 'Reload' }).click();
+
+    await expect(loads(page)).toHaveText('2');
+    await expect(page.getByRole('dialog')).toBeHidden();
+    expect(await storedVersion(page)).toBe('v2');
+  });
+
+  test('promptOnChunkError asks before reloading when a chunk is gone', async ({
+    page
+  }) => {
+    const server = await deployServer(page, 'v1');
+    await page.goto('/?prompt=1&promptOnChunkError=1');
+    await expect(page.getByTestId('lazy')).toBeVisible();
+
+    server.deploy('v1', 'v2');
+    await breakLazyChunk(page, 1);
+    await page.reload();
+
+    const dialog = page.getByRole('dialog');
+    await expect(dialog).toContainText('could not load');
+    expect(await page.evaluate(() => sessionStorage.getItem('loads'))).toBe(
+      '2'
+    );
+
+    await dialog.getByRole('button', { name: 'Reload' }).click();
+
+    await expect(loads(page)).toHaveText('3');
+    await expect(page.getByTestId('lazy')).toBeVisible();
+    expect(await storedVersion(page)).toBe('v2');
+  });
+});

docs/demo-light.png

@@ -0,0 +1,49 @@
+import { expect, test } from '@playwright/test';
+
+test('a simulated deploy is offered through the dialog and applied on Reload', async ({
+  page
+}) => {
+  await page.goto('./');
+  await expect(page.getByTestId('stored')).toHaveText('v1');
+
+  await page.getByRole('button', { name: 'Deploy new version' }).click();
+  await expect(page.getByTestId('deployed')).toHaveText('v2');
+
+  const dialog = page.getByRole('dialog', {
+    name: 'A new version is available'
+  });
+  await expect(dialog).toBeVisible({ timeout: 10_000 });
+  await dialog.getByRole('button', { name: 'Reload' }).click();
+
+  await expect(page.getByTestId('loads')).toHaveText('2');
+  await expect(page.getByTestId('running')).toHaveText('v2');
+  await expect(page.getByTestId('stored')).toHaveText('v2');
+  await expect(page.getByText('Cache Storage is empty')).toBeVisible();
+});
+
+test('a lazy chunk removed by a deploy prompts with the error message', async ({
+  page
+}) => {
+  await page.goto('./?duration=0');
+  await page.getByRole('button', { name: 'Deploy new version' }).click();
+  await page.getByRole('button', { name: 'Open reports (lazy chunk)' }).click();
+
+  const dialog = page.getByRole('dialog');
+  await expect(dialog).toContainText('could not load');
+  await dialog.getByRole('button', { name: 'Reload' }).click();
+
+  await expect(page.getByTestId('running')).toHaveText('v2');
+  await page.getByRole('button', { name: 'Open reports (lazy chunk)' }).click();
+  await expect(page.getByTestId('reports')).toHaveText(/v2 chunk/);
+});
+
+test('the custom banner component replaces the dialog', async ({ page }) => {
+  await page.goto('./?prompt=banner&duration=3000');
+  await page.getByRole('button', { name: 'Deploy new version' }).click();
+
+  const banner = page.getByRole('status');
+  await expect(banner).toContainText('v2 is ready', { timeout: 10_000 });
+  await banner.getByRole('button', { name: 'Dismiss' }).click();
+  await expect(banner).toBeHidden();
+  await expect(page.getByTestId('is-latest')).toHaveText('false');
+});

e2e/clearBrowserCache.spec.ts

@@ -6,7 +6,13 @@ import tseslint from 'typescript-eslint';
 
 export default tseslint.config(
   {
-    ignores: ['**/dist', 'coverage', 'playwright-report', 'test-results']
+    ignores: [
+      '**/dist',
+      '**/dist-demo',
+      'coverage',
+      'playwright-report',
+      'test-results'
+    ]
   },
   js.configs.recommended,
   tseslint.configs.recommended,

e2e/demo.spec.ts

@@ -11,7 +11,17 @@ pnpm example:dev
 
 Query parameters configure the boundary, so one build covers every scenario:
 
-| Parameter  | Effect                                  |
-| :--------- | :-------------------------------------- |
-| `auto=1`   | Reload as soon as a new build is found. |
-| `duration` | Polling interval in ms.                 |
+| Parameter         | Effect                                              |
+| :---------------- | :-------------------------------------------------- |
+| `auto=1`          | Reload as soon as a new build is found.             |
+| `duration`        | Polling interval in ms.                             |
+| `prompt=1`        | Show the built-in `UpdatePrompt` dialog.            |
+| `promptOnError=1` | Prompt instead of reloading on a stale-chunk error. |
+
+## GitHub Pages demo
+
+`pnpm demo:dev` and `pnpm demo:build` set `VITE_DEMO=1`, which swaps the entry
+for `src/demo`: a playground with a **Deploy new version** button, live boundary
+props, the tab's state and an event log. A fetch shim stands in for the server,
+since Pages serves static files only. `e2e/demo.spec.ts` covers it under the
+same `/react-clear-browser-cache/` sub-path that Pages uses.