@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 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
- # Temporary Holding Version
1
+ # twake-react-new-version
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
+ };
@@ -0,0 +1,2 @@
1
+ export { NewVersionDialog, type NewVersionDialogProps } from './NewVersionDialog';
2
+ export { CHECK_VERSION_EVENT, fetchServedBuild, isNewBuild, requestVersionCheck } from './version';
package/dist/index.js ADDED
@@ -0,0 +1,2 @@
1
+ export { NewVersionDialog } from './NewVersionDialog';
2
+ export { CHECK_VERSION_EVENT, fetchServedBuild, isNewBuild, requestVersionCheck } from './version';
@@ -0,0 +1,8 @@
1
+ {
2
+ "twakeNewVersion": {
3
+ "title": "Neue Version verfügbar",
4
+ "body": "Laden Sie die Seite neu, um die neueste Version von %{appName} zu verwenden.",
5
+ "reload": "Neu laden",
6
+ "notNow": "Nicht jetzt"
7
+ }
8
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "twakeNewVersion": {
3
+ "title": "New version available",
4
+ "body": "Reload the page to use the latest version of %{appName}.",
5
+ "reload": "Reload",
6
+ "notNow": "Not now"
7
+ }
8
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "twakeNewVersion": {
3
+ "title": "Nueva versión disponible",
4
+ "body": "Recarga la página para usar la última versión de %{appName}.",
5
+ "reload": "Recargar",
6
+ "notNow": "Ahora no"
7
+ }
8
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "twakeNewVersion": {
3
+ "title": "Nouvelle version disponible",
4
+ "body": "Rechargez la page pour utiliser la dernière version de %{appName}.",
5
+ "reload": "Recharger",
6
+ "notNow": "Pas maintenant"
7
+ }
8
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "twakeNewVersion": {
3
+ "title": "Nuova versione disponibile",
4
+ "body": "Ricarica la pagina per usare l'ultima versione di %{appName}.",
5
+ "reload": "Ricarica",
6
+ "notNow": "Non ora"
7
+ }
8
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "twakeNewVersion": {
3
+ "title": "Доступна новая версия",
4
+ "body": "Перезагрузите страницу, чтобы использовать последнюю версию %{appName}.",
5
+ "reload": "Перезагрузить",
6
+ "notNow": "Не сейчас"
7
+ }
8
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "twakeNewVersion": {
3
+ "title": "Đã có phiên bản mới",
4
+ "body": "Tải lại trang để dùng phiên bản mới nhất của %{appName}.",
5
+ "reload": "Tải lại",
6
+ "notNow": "Để sau"
7
+ }
8
+ }
@@ -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;
@@ -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
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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
+ }