@hashsome/runtime 0.3.0 → 0.4.0

package/dist/app/entry.client.js

@@ -2,6 +2,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { startTransition, StrictMode } from 'react';
 import { hydrateRoot } from 'react-dom/client';
 import { HydratedRouter } from 'react-router/dom';
+import { watchBrowserForNewVersion } from './version-watch.js';
 startTransition(() => {
     hydrateRoot(document, _jsx(StrictMode, { children: _jsx(HydratedRouter, {}) }));
 });
+// A dashboard left open for weeks is reloaded once a newer build is being served.
+watchBrowserForNewVersion();

package/dist/app/version-watch.d.ts

@@ -0,0 +1,27 @@
+/** The id of the build this page came from; undefined in dev, where nothing is watched. */
+export declare const PAGE_BUILD_ID: string | undefined;
+export interface VersionWatchOptions {
+    /** The build this page is. */
+    buildId: string;
+    /** The build being served now; undefined when it cannot be told (offline, an old server). */
+    read: () => Promise<string | undefined>;
+    reload: () => void;
+    /** How often to ask while the page is open. Default one minute. */
+    intervalMs?: number;
+    /** Calls the function when the page may have been asleep: shown again, or back online. */
+    onWake: (check: () => void) => () => void;
+    /** Remembers when this page last reloaded for a new version, across the reload. */
+    lastReload: {
+        get: () => number | undefined;
+        set: (time: number) => void;
+    };
+    now?: () => number;
+}
+/**
+ * Reloads the page when the server is serving a different build than the one it was loaded from. A
+ * tablet or wall display keeps a dashboard open for weeks, and a deployment replaces the server
+ * under it without replacing the page. Returns a function that stops watching.
+ */
+export declare function watchForNewVersion(options: VersionWatchOptions): () => void;
+/** Starts watching in the browser, for a production build. Does nothing in dev. */
+export declare function watchBrowserForNewVersion(): void;

package/dist/app/version-watch.js

@@ -0,0 +1,84 @@
+import { VERSION_PATH } from '../src/build-id.js';
+/** The id of the build this page came from; undefined in dev, where nothing is watched. */
+export const PAGE_BUILD_ID = typeof HASHSOME_BUILD_ID === 'undefined' ? undefined : HASHSOME_BUILD_ID;
+/** Never reload twice within this long: if the server keeps answering with another id (a stale cache
+ * in front of it), the page would otherwise reload for ever. */
+const REPEAT_MS = 30_000;
+/**
+ * Reloads the page when the server is serving a different build than the one it was loaded from. A
+ * tablet or wall display keeps a dashboard open for weeks, and a deployment replaces the server
+ * under it without replacing the page. Returns a function that stops watching.
+ */
+export function watchForNewVersion(options) {
+    const now = options.now ?? Date.now;
+    let busy = false;
+    const check = () => {
+        if (busy) {
+            return;
+        }
+        busy = true;
+        options.read().then((served) => {
+            busy = false;
+            if (served === undefined || served === options.buildId) {
+                return;
+            }
+            const last = options.lastReload.get();
+            if (last !== undefined && now() - last < REPEAT_MS) {
+                return;
+            }
+            options.lastReload.set(now());
+            options.reload();
+        }, () => {
+            busy = false;
+        });
+    };
+    const timer = setInterval(check, options.intervalMs ?? 60_000);
+    const stopWake = options.onWake(check);
+    return () => {
+        clearInterval(timer);
+        stopWake();
+    };
+}
+/** Starts watching in the browser, for a production build. Does nothing in dev. */
+export function watchBrowserForNewVersion() {
+    const buildId = PAGE_BUILD_ID;
+    if (buildId === undefined) {
+        return;
+    }
+    const KEY = 'hashsome:reloaded-at';
+    watchForNewVersion({
+        buildId,
+        read: async () => {
+            const response = await fetch(VERSION_PATH, { cache: 'no-store' });
+            return response.ok ? (await response.json()).id : undefined;
+        },
+        reload: () => window.location.reload(),
+        onWake: (check) => {
+            const onVisible = () => document.visibilityState === 'visible' && check();
+            document.addEventListener('visibilitychange', onVisible);
+            window.addEventListener('online', check);
+            return () => {
+                document.removeEventListener('visibilitychange', onVisible);
+                window.removeEventListener('online', check);
+            };
+        },
+        lastReload: {
+            get: () => {
+                try {
+                    return Number(sessionStorage.getItem(KEY)) || undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            },
+            set: (time) => {
+                try {
+                    sessionStorage.setItem(KEY, String(time));
+                }
+                catch {
+                    // Without storage the guard is the page's own memory only, which a reload loses.
+                }
+            },
+        },
+    });
+}

package/dist/src/build-id.d.ts

@@ -0,0 +1,12 @@
+import type { Plugin } from 'vite';
+/** Where a build records its id, next to the client files, and where the server tells it. */
+export declare const VERSION_FILE = "version.json";
+export declare const VERSION_PATH = "/_hashsome/version";
+/** One per `hashsome build` run: the same for everything that run produces. */
+export declare const buildId: () => string;
+/**
+ * Gives a production build an id that its client knows (as `HASHSOME_BUILD_ID`) and the server
+ * can tell (the client directory gets a `version.json`). A page left open compares the two and
+ * reloads when a newer build is being served. Dev builds have neither, so nothing is watched there.
+ */
+export declare function hashsomeBuildId(): Plugin;

package/dist/src/build-id.js

@@ -0,0 +1,29 @@
+/** Where a build records its id, next to the client files, and where the server tells it. */
+export const VERSION_FILE = 'version.json';
+export const VERSION_PATH = '/_hashsome/version';
+let id;
+/** One per `hashsome build` run: the same for everything that run produces. */
+export const buildId = () => (id ??= process.env.HASHSOME_BUILD_ID || Date.now().toString(36));
+/**
+ * Gives a production build an id that its client knows (as `HASHSOME_BUILD_ID`) and the server
+ * can tell (the client directory gets a `version.json`). A page left open compares the two and
+ * reloads when a newer build is being served. Dev builds have neither, so nothing is watched there.
+ */
+export function hashsomeBuildId() {
+    return {
+        name: 'hashsome:build-id',
+        apply: 'build',
+        config: () => ({ define: { HASHSOME_BUILD_ID: JSON.stringify(buildId()) } }),
+        generateBundle() {
+            // The server's own build has no use for it; the client's output is what gets served.
+            if (this.environment && this.environment.name !== 'client') {
+                return;
+            }
+            this.emitFile({
+                type: 'asset',
+                fileName: VERSION_FILE,
+                source: JSON.stringify({ id: buildId() }),
+            });
+        },
+    };
+}

package/dist/src/server/production.js

@@ -1,16 +1,40 @@
 import express, {} from 'express';
 import { createServer } from 'node:http';
+import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { VERSION_FILE, VERSION_PATH } from '../build-id.js';
 import { serveAsset } from './assets.js';
 import { Proxy } from './proxy.js';
 import { startIntegrations } from './integrations.js';
 import { attachWebSocket } from './websocket.js';
+/** The id the build left in the client directory; none for a client built without one. */
+function readVersion(clientDir) {
+    try {
+        const { id } = JSON.parse(readFileSync(join(clientDir, VERSION_FILE), 'utf8'));
+        return typeof id === 'string' && id !== '' ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function createApp(clientDir, integrations = []) {
     const app = express();
     app.disable('x-powered-by');
     app.get('/healthz', (_req, res) => {
         res.json({ status: 'ok' });
     });
+    // Which build this is, for a page that has been open a while to compare with its own and reload.
+    // Never cached: a stale answer is exactly what it is there to avoid.
+    const version = readVersion(clientDir);
+    app.get(VERSION_PATH, (_req, res) => {
+        res.setHeader('cache-control', 'no-store');
+        if (version) {
+            res.json({ id: version });
+        }
+        else {
+            res.status(404).end();
+        }
+    });
     app.use((req, res, next) => {
         serveAsset(integrations, req, res).then((served) => (served ? undefined : next()), next);
     });

package/dist/src/vite-config.js

@@ -1,5 +1,6 @@
 import { reactRouter } from '@react-router/dev/vite';
 import { defineConfig } from 'vite';
+import { hashsomeBuildId } from './build-id.js';
 /**
  * Sensible default, re-exported by the project's own `vite.config.ts` (the React Router plugin
  * requires a config file at the project root). Server settings and the dev proxy are supplied
@@ -11,7 +12,7 @@ import { defineConfig } from 'vite';
  * ("Expected build manifest").
  */
 export default defineConfig(() => ({
-    plugins: [reactRouter()],
+    plugins: [reactRouter(), hashsomeBuildId()],
     // React Router's SPA prerender starts a private preview server; pin it to IPv4 so it is
     // reachable in containers where `localhost` resolves to ::1.
     preview: { host: '127.0.0.1' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashsome/runtime",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Server + CLI that serves a project's own dashboards",
   "type": "module",
   "exports": {
@@ -38,8 +38,8 @@
     "jsdom": "30.1.1"
   },
   "dependencies": {
-    "@hashsome/core": "0.3.0",
-    "@hashsome/ui": "0.3.0",
+    "@hashsome/core": "0.4.0",
+    "@hashsome/ui": "0.4.0",
     "@react-router/dev": "8.4.0",
     "express": "5.2.1",
     "react": "19.3.0",