@linagora/twake-react-new-version 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +7 -0
- package/README.md +72 -2
- package/dist/NewVersionDialog.d.ts +17 -0
- package/dist/NewVersionDialog.js +95 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +2 -0
- package/dist/locales/de.json +8 -0
- package/dist/locales/en.json +8 -0
- package/dist/locales/es.json +8 -0
- package/dist/locales/fr.json +8 -0
- package/dist/locales/it.json +8 -0
- package/dist/locales/ru.json +8 -0
- package/dist/locales/vi.json +8 -0
- package/dist/version.d.ts +15 -0
- package/dist/version.js +29 -0
- package/package.json +62 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# @linagora/twake-react-new-version 1.0.0 (2026-11-13)
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
### Features
|
|
5
|
+
|
|
6
|
+
* **twake-react-new-version:** Offer a reload when a newer build is served ([b2f3f64](https://github.com/linagora/twake-libs/commit/b2f3f644536635a5b303f0e27f1f0a911336188f))
|
|
7
|
+
* **twake-react-new-version:** Read the build the server serves ([fb73480](https://github.com/linagora/twake-libs/commit/fb734805a670d7fd43f10e97a29895c8606f665e))
|
package/README.md
CHANGED
|
@@ -1,3 +1,73 @@
|
|
|
1
|
-
#
|
|
1
|
+
# twake-react-new-version
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Tells the user of a Twake application that the server now serves a newer build than the one running in the tab, and offers to reload the page.
|
|
4
|
+
|
|
5
|
+
## Requirements
|
|
6
|
+
|
|
7
|
+
You need to use Node 24+
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install @linagora/twake-react-new-version
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
`@linagora/twake-mui`, `twake-i18n`, `react` and `react-dom` are peer dependencies.
|
|
16
|
+
|
|
17
|
+
## What the app serves
|
|
18
|
+
|
|
19
|
+
Each build has its own id (the commit in CI, for instance). The app:
|
|
20
|
+
|
|
21
|
+
- writes it in the bundle, so the running tab knows its own build;
|
|
22
|
+
- serves it at `/version.json` as `{ "build": "<id>" }`, with `Cache-Control: no-store`.
|
|
23
|
+
|
|
24
|
+
The id must be in the bundle, not read at runtime from a file served next to it: during a rollout a tab may get the bundle of the old server and that file from the new one, and would never be offered a reload.
|
|
25
|
+
|
|
26
|
+
## Usage
|
|
27
|
+
|
|
28
|
+
Mount the dialog once, under the app's `I18n` and `TwakeMuiThemeProvider`:
|
|
29
|
+
|
|
30
|
+
```tsx
|
|
31
|
+
import { NewVersionDialog } from '@linagora/twake-react-new-version'
|
|
32
|
+
|
|
33
|
+
const AppVersion = (): React.ReactElement => (
|
|
34
|
+
<NewVersionDialog running={BUILD_ID} appName="Twake Mail" />
|
|
35
|
+
)
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
When a lazy chunk fails to load, the usual sign of a tab older than the served build, ask for a check at once:
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
import { requestVersionCheck } from '@linagora/twake-react-new-version'
|
|
42
|
+
|
|
43
|
+
const ComposerForm = lazy(() =>
|
|
44
|
+
import('./ComposerForm').catch((error: unknown) => {
|
|
45
|
+
requestVersionCheck()
|
|
46
|
+
throw error
|
|
47
|
+
})
|
|
48
|
+
)
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### When it checks
|
|
52
|
+
|
|
53
|
+
Every 10 minutes, when the tab gets the focus, becomes visible again or comes back online, and on `requestVersionCheck()`. One check at a time, and at most one every 30 seconds but the ones `requestVersionCheck()` asks for: a framed app gets the focus at each click of its host. Never at mount: the page just loaded is the served build. An error, the network, or an answer that is not that JSON (a dev server answers `index.html`) is no new build.
|
|
54
|
+
|
|
55
|
+
### What the user sees
|
|
56
|
+
|
|
57
|
+
« New version available », with « Not now » and « Reload ». « Not now », Escape or a click outside decline that build for the life of the tab: the dialog comes back only for a build not declined yet, so a rollback to a declined build is not offered again.
|
|
58
|
+
|
|
59
|
+
### Props
|
|
60
|
+
|
|
61
|
+
- `running`: the build id of this bundle
|
|
62
|
+
- `appName`: the name shown in the text, such as `Twake Mail`
|
|
63
|
+
- `fetchServed()`: reads the served build id, `fetchServedBuild` by default
|
|
64
|
+
- `reload()`: `window.location.reload` by default
|
|
65
|
+
- `intervalMs`: time between two checks, 10 minutes by default
|
|
66
|
+
|
|
67
|
+
### Texts
|
|
68
|
+
|
|
69
|
+
`en`, `fr`, `de`, `es`, `it`, `ru` and `vi`, added to the app's `I18n` under `twakeNewVersion`; English for any other language.
|
|
70
|
+
|
|
71
|
+
### Detection alone
|
|
72
|
+
|
|
73
|
+
`fetchServedBuild(url = '/version.json')` and `isNewBuild(running, served)` are exported for an app that wants another surface than the dialog.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import React from 'react';
|
|
2
|
+
export interface NewVersionDialogProps {
|
|
3
|
+
/** The build id of this bundle, the one `/version.json` names once served */
|
|
4
|
+
running: string;
|
|
5
|
+
/** The name shown in the text, such as `Twake Mail` */
|
|
6
|
+
appName: string;
|
|
7
|
+
fetchServed?: () => Promise<string | null>;
|
|
8
|
+
reload?: () => void;
|
|
9
|
+
intervalMs?: number;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* « New version available »: offers a reload to a tab that runs an older
|
|
13
|
+
* build than the served one. « Not now », Escape or a click outside decline
|
|
14
|
+
* that build for the life of the tab: the dialog comes back only for a build
|
|
15
|
+
* not declined yet. Mount it once, under the app's `I18n` and twake-mui theme
|
|
16
|
+
*/
|
|
17
|
+
export declare const NewVersionDialog: ({ running, appName, fetchServed, reload, intervalMs }: NewVersionDialogProps) => React.ReactElement;
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
import React, { useEffect, useId, useRef, useState } from 'react';
|
|
2
|
+
import { Button, Dialog, DialogActions, DialogContent, DialogContentText, DialogTitle } from '@linagora/twake-mui';
|
|
3
|
+
import { useExtendI18n, useI18n } from 'twake-i18n';
|
|
4
|
+
import de from './locales/de.json';
|
|
5
|
+
import en from './locales/en.json';
|
|
6
|
+
import es from './locales/es.json';
|
|
7
|
+
import fr from './locales/fr.json';
|
|
8
|
+
import it from './locales/it.json';
|
|
9
|
+
import ru from './locales/ru.json';
|
|
10
|
+
import vi from './locales/vi.json';
|
|
11
|
+
import { CHECK_VERSION_EVENT, fetchServedBuild, isNewBuild } from './version';
|
|
12
|
+
const locales = { de, en, es, fr, it, ru, vi };
|
|
13
|
+
const MINUTE = 60000;
|
|
14
|
+
const MIN_GAP_MS = 30000;
|
|
15
|
+
/**
|
|
16
|
+
* Runs `check` every `intervalMs`, and whenever the tab may have missed a
|
|
17
|
+
* deployment: it gets the focus, becomes visible again, comes back online, or
|
|
18
|
+
* the app asks for it (`requestVersionCheck`). Not at mount: the page just
|
|
19
|
+
* loaded is the served build. One check at a time, and at most one per
|
|
20
|
+
* `MIN_GAP_MS` but the ones the app asks for: a framed app gets the focus at
|
|
21
|
+
* each click of its host
|
|
22
|
+
*/
|
|
23
|
+
const useVersionChecks = (check, intervalMs) => {
|
|
24
|
+
// The listeners stay in place while `check` changes with each render
|
|
25
|
+
const latestCheck = useRef(check);
|
|
26
|
+
latestCheck.current = check;
|
|
27
|
+
// Refs, not effect locals: the guard holds when `intervalMs` changes
|
|
28
|
+
const isRunning = useRef(false);
|
|
29
|
+
const lastRun = useRef(-Infinity);
|
|
30
|
+
useEffect(() => {
|
|
31
|
+
const run = (isAsked = false) => {
|
|
32
|
+
const now = Date.now();
|
|
33
|
+
if (isRunning.current)
|
|
34
|
+
return;
|
|
35
|
+
if (!isAsked && now - lastRun.current < MIN_GAP_MS)
|
|
36
|
+
return;
|
|
37
|
+
isRunning.current = true;
|
|
38
|
+
lastRun.current = now;
|
|
39
|
+
void latestCheck.current().finally(() => {
|
|
40
|
+
isRunning.current = false;
|
|
41
|
+
});
|
|
42
|
+
};
|
|
43
|
+
const onEvent = () => run();
|
|
44
|
+
const onAsked = () => run(true);
|
|
45
|
+
const onVisible = () => {
|
|
46
|
+
if (document.visibilityState === 'visible')
|
|
47
|
+
run();
|
|
48
|
+
};
|
|
49
|
+
const timer = window.setInterval(onEvent, intervalMs);
|
|
50
|
+
const events = ['focus', 'online'];
|
|
51
|
+
events.forEach(name => window.addEventListener(name, onEvent));
|
|
52
|
+
window.addEventListener(CHECK_VERSION_EVENT, onAsked);
|
|
53
|
+
document.addEventListener('visibilitychange', onVisible);
|
|
54
|
+
return () => {
|
|
55
|
+
window.clearInterval(timer);
|
|
56
|
+
events.forEach(name => window.removeEventListener(name, onEvent));
|
|
57
|
+
window.removeEventListener(CHECK_VERSION_EVENT, onAsked);
|
|
58
|
+
document.removeEventListener('visibilitychange', onVisible);
|
|
59
|
+
};
|
|
60
|
+
}, [intervalMs]);
|
|
61
|
+
};
|
|
62
|
+
/**
|
|
63
|
+
* « New version available »: offers a reload to a tab that runs an older
|
|
64
|
+
* build than the served one. « Not now », Escape or a click outside decline
|
|
65
|
+
* that build for the life of the tab: the dialog comes back only for a build
|
|
66
|
+
* not declined yet. Mount it once, under the app's `I18n` and twake-mui theme
|
|
67
|
+
*/
|
|
68
|
+
export const NewVersionDialog = ({ running, appName, fetchServed = fetchServedBuild, reload = () => window.location.reload(), intervalMs = 10 * MINUTE }) => {
|
|
69
|
+
const { t, lang } = useI18n();
|
|
70
|
+
useExtendI18n({ [lang]: locales[lang] ?? locales.en });
|
|
71
|
+
const titleId = useId();
|
|
72
|
+
const [offered, setOffered] = useState(null);
|
|
73
|
+
// Read only in events, never drawn: a ref, not state
|
|
74
|
+
const declined = useRef(new Set());
|
|
75
|
+
useVersionChecks(async () => {
|
|
76
|
+
if (offered !== null)
|
|
77
|
+
return;
|
|
78
|
+
const served = await fetchServed().catch(() => null);
|
|
79
|
+
if (isNewBuild(running, served) && !declined.current.has(served)) {
|
|
80
|
+
setOffered(served);
|
|
81
|
+
}
|
|
82
|
+
}, intervalMs);
|
|
83
|
+
const notNow = () => {
|
|
84
|
+
if (offered !== null)
|
|
85
|
+
declined.current.add(offered);
|
|
86
|
+
setOffered(null);
|
|
87
|
+
};
|
|
88
|
+
return (React.createElement(Dialog, { open: offered !== null, onClose: notNow, size: "small", "aria-labelledby": titleId, "data-testid": "new-version-dialog" },
|
|
89
|
+
React.createElement(DialogTitle, { id: titleId }, t('twakeNewVersion.title')),
|
|
90
|
+
React.createElement(DialogContent, null,
|
|
91
|
+
React.createElement(DialogContentText, null, t('twakeNewVersion.body').replace('%{appName}', appName))),
|
|
92
|
+
React.createElement(DialogActions, null,
|
|
93
|
+
React.createElement(Button, { variant: "outlined", "data-testid": "new-version-not-now", onClick: notNow }, t('twakeNewVersion.notNow')),
|
|
94
|
+
React.createElement(Button, { variant: "contained", color: "primary", "data-testid": "new-version-reload", onClick: reload }, t('twakeNewVersion.reload')))));
|
|
95
|
+
};
|
package/dist/index.d.ts
ADDED
package/dist/index.js
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/** The window event that asks the dialog to check the served build at once */
|
|
2
|
+
export declare const CHECK_VERSION_EVENT = "twake:check-version";
|
|
3
|
+
/**
|
|
4
|
+
* Asks for a check now: call it when a lazy chunk fails to load, the usual
|
|
5
|
+
* sign of a tab running an older build than the served one
|
|
6
|
+
*/
|
|
7
|
+
export declare const requestVersionCheck: () => void;
|
|
8
|
+
/**
|
|
9
|
+
* The id of the build the server serves now, read in `{ "build": "…" }`.
|
|
10
|
+
* Null when it cannot tell: an error, the network, or a page that is not that
|
|
11
|
+
* JSON (a dev server answers index.html for any path)
|
|
12
|
+
*/
|
|
13
|
+
export declare const fetchServedBuild: (url?: string, fetchFn?: typeof fetch) => Promise<string | null>;
|
|
14
|
+
/** True when the server serves a build other than the one running here */
|
|
15
|
+
export declare const isNewBuild: (running: string, served: string | null) => served is string;
|
package/dist/version.js
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/** The window event that asks the dialog to check the served build at once */
|
|
2
|
+
export const CHECK_VERSION_EVENT = 'twake:check-version';
|
|
3
|
+
/**
|
|
4
|
+
* Asks for a check now: call it when a lazy chunk fails to load, the usual
|
|
5
|
+
* sign of a tab running an older build than the served one
|
|
6
|
+
*/
|
|
7
|
+
export const requestVersionCheck = () => {
|
|
8
|
+
window.dispatchEvent(new Event(CHECK_VERSION_EVENT));
|
|
9
|
+
};
|
|
10
|
+
/**
|
|
11
|
+
* The id of the build the server serves now, read in `{ "build": "…" }`.
|
|
12
|
+
* Null when it cannot tell: an error, the network, or a page that is not that
|
|
13
|
+
* JSON (a dev server answers index.html for any path)
|
|
14
|
+
*/
|
|
15
|
+
export const fetchServedBuild = async (url = '/version.json', fetchFn = fetch) => {
|
|
16
|
+
try {
|
|
17
|
+
const response = await fetchFn(url, { cache: 'no-store' });
|
|
18
|
+
if (!response.ok)
|
|
19
|
+
return null;
|
|
20
|
+
const body = await response.json();
|
|
21
|
+
const build = body?.build;
|
|
22
|
+
return typeof build === 'string' && build !== '' ? build : null;
|
|
23
|
+
}
|
|
24
|
+
catch {
|
|
25
|
+
return null;
|
|
26
|
+
}
|
|
27
|
+
};
|
|
28
|
+
/** True when the server serves a build other than the one running here */
|
|
29
|
+
export const isNewBuild = (running, served) => served !== null && served !== '' && served !== running;
|
package/package.json
CHANGED
|
@@ -1,6 +1,64 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@linagora/twake-react-new-version",
|
|
3
|
-
"
|
|
4
|
-
"
|
|
5
|
-
"description": "
|
|
6
|
-
|
|
3
|
+
"type": "module",
|
|
4
|
+
"version": "1.0.0",
|
|
5
|
+
"description": "Tells the user of a Twake application that a new version is served, and offers a reload",
|
|
6
|
+
"author": "Twake",
|
|
7
|
+
"license": "MIT",
|
|
8
|
+
"engines": {
|
|
9
|
+
"node": "24.x"
|
|
10
|
+
},
|
|
11
|
+
"repository": {
|
|
12
|
+
"type": "git",
|
|
13
|
+
"url": "https://github.com/linagora/twake-libs.git",
|
|
14
|
+
"directory": "packages/twake-react-new-version"
|
|
15
|
+
},
|
|
16
|
+
"exports": {
|
|
17
|
+
".": {
|
|
18
|
+
"types": "./dist/index.d.ts",
|
|
19
|
+
"import": "./dist/index.js",
|
|
20
|
+
"default": "./dist/index.js"
|
|
21
|
+
}
|
|
22
|
+
},
|
|
23
|
+
"main": "dist/index.js",
|
|
24
|
+
"types": "dist/index.d.ts",
|
|
25
|
+
"files": [
|
|
26
|
+
"dist",
|
|
27
|
+
"CHANGELOG.md",
|
|
28
|
+
"README.md"
|
|
29
|
+
],
|
|
30
|
+
"publishConfig": {
|
|
31
|
+
"access": "public"
|
|
32
|
+
},
|
|
33
|
+
"scripts": {
|
|
34
|
+
"build": "tsc -b tsconfig.build.json",
|
|
35
|
+
"start": "tsc -b tsconfig.build.json --watch",
|
|
36
|
+
"test": "vitest run",
|
|
37
|
+
"clean": "rm -rf dist"
|
|
38
|
+
},
|
|
39
|
+
"peerDependencies": {
|
|
40
|
+
"@linagora/twake-mui": ">=10.0.0",
|
|
41
|
+
"react": "^18 || ^19",
|
|
42
|
+
"react-dom": "^18 || ^19",
|
|
43
|
+
"twake-i18n": ">=0.6.0"
|
|
44
|
+
},
|
|
45
|
+
"devDependencies": {
|
|
46
|
+
"@emotion/react": "^11.14.0",
|
|
47
|
+
"@emotion/styled": "^11.14.0",
|
|
48
|
+
"@linagora/twake-icons": "^2.13.0",
|
|
49
|
+
"@linagora/twake-mui": "^10.3.0",
|
|
50
|
+
"@mui/lab": "^9.0.0-beta.6",
|
|
51
|
+
"@mui/material": "^9.4.0",
|
|
52
|
+
"@testing-library/jest-dom": "^6.6.3",
|
|
53
|
+
"@testing-library/react": "^16.3.0",
|
|
54
|
+
"@testing-library/user-event": "^14.6.1",
|
|
55
|
+
"@types/react": "^18.3.0",
|
|
56
|
+
"@types/react-dom": "^18.3.0",
|
|
57
|
+
"cozy-tsconfig": "^2.0.0",
|
|
58
|
+
"jsdom": "^26.1.0",
|
|
59
|
+
"react": "^18.3.0",
|
|
60
|
+
"react-dom": "^18.3.0",
|
|
61
|
+
"twake-i18n": "^0.6.0",
|
|
62
|
+
"vitest": "5.0.1"
|
|
63
|
+
}
|
|
64
|
+
}
|