@rsc-kit/core 0.11.0 → 0.12.0

package/dist/js/updateStore.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Whether a newer build is live while this page is still running the old one.
+ *
+ * Free of React for the same reason onlineStore is: the value arrives from a
+ * service worker message, which has nothing to do with rendering, and the hook
+ * that reads it lives next door.
+ *
+ * The situation it reports is real rather than theoretical. This package's
+ * worker activates immediately rather than waiting for every tab to close, and
+ * activating sweeps the previous build's cache — so a page that has been open
+ * across a deploy is running javascript whose remaining chunks are gone. It
+ * works until it navigates somewhere that needs one.
+ */
+export declare function isUpdated(): boolean;
+export declare function subscribeToUpdates(callback: () => void): () => void;
+/** The server render's answer. A fresh document is by definition not stale. */
+export declare function updatedOnServer(): boolean;

package/dist/js/updateStore.js

@@ -0,0 +1,44 @@
+/**
+ * Whether a newer build is live while this page is still running the old one.
+ *
+ * Free of React for the same reason onlineStore is: the value arrives from a
+ * service worker message, which has nothing to do with rendering, and the hook
+ * that reads it lives next door.
+ *
+ * The situation it reports is real rather than theoretical. This package's
+ * worker activates immediately rather than waiting for every tab to close, and
+ * activating sweeps the previous build's cache — so a page that has been open
+ * across a deploy is running javascript whose remaining chunks are gone. It
+ * works until it navigates somewhere that needs one.
+ */
+let updated = false;
+const listeners = new Set();
+/** A boolean, so React compares snapshots by value and does not loop. */
+function announce() {
+    if (updated)
+        return;
+    updated = true;
+    listeners.forEach((fn) => fn());
+}
+if (typeof navigator !== 'undefined' && 'serviceWorker' in navigator) {
+    navigator.serviceWorker.addEventListener('message', (event) => {
+        if (event.data?.type === 'rsc-kit:updated')
+            announce();
+    });
+    // A worker that took control after this page loaded is the same news by
+    // another route — it fires when the page was open across a deploy and the
+    // message was posted before this listener existed.
+    navigator.serviceWorker.addEventListener('controllerchange', announce);
+}
+export function isUpdated() {
+    return updated;
+}
+export function subscribeToUpdates(callback) {
+    listeners.add(callback);
+    return () => listeners.delete(callback);
+}
+/** The server render's answer. A fresh document is by definition not stale. */
+export function updatedOnServer() {
+    return false;
+}
+//# sourceMappingURL=updateStore.js.map

package/dist/js/updateStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateStore.js","sourceRoot":"","sources":["../../src/js/updateStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,IAAI,OAAO,GAAG,KAAK,CAAA;AACnB,MAAM,SAAS,GAAG,IAAI,GAAG,EAAc,CAAA;AAEvC,yEAAyE;AACzE,SAAS,QAAQ;IACf,IAAI,OAAO;QAAE,OAAM;IAEnB,OAAO,GAAG,IAAI,CAAA;IACd,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAA;AACjC,CAAC;AAED,IAAI,OAAO,SAAS,KAAK,WAAW,IAAI,eAAe,IAAI,SAAS,EAAE,CAAC;IACrE,SAAS,CAAC,aAAa,CAAC,gBAAgB,CAAC,SAAS,EAAE,CAAC,KAAmB,EAAE,EAAE;QAC1E,IAAK,KAAK,CAAC,IAAiC,EAAE,IAAI,KAAK,iBAAiB;YAAE,QAAQ,EAAE,CAAA;IACtF,CAAC,CAAC,CAAA;IAEF,wEAAwE;IACxE,0EAA0E;IAC1E,mDAAmD;IACnD,SAAS,CAAC,aAAa,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAA;AACxE,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO,OAAO,CAAA;AAChB,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,QAAoB;IACrD,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAEvB,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;AACzC,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,CAAA;AACd,CAAC","sourcesContent":["/**\n * Whether a newer build is live while this page is still running the old one.\n *\n * Free of React for the same reason onlineStore is: the value arrives from a\n * service worker message, which has nothing to do with rendering, and the hook\n * that reads it lives next door.\n *\n * The situation it reports is real rather than theoretical. This package's\n * worker activates immediately rather than waiting for every tab to close, and\n * activating sweeps the previous build's cache — so a page that has been open\n * across a deploy is running javascript whose remaining chunks are gone. It\n * works until it navigates somewhere that needs one.\n */\n\nlet updated = false\nconst listeners = new Set<() => void>()\n\n/** A boolean, so React compares snapshots by value and does not loop. */\nfunction announce(): void {\n  if (updated) return\n\n  updated = true\n  listeners.forEach((fn) => fn())\n}\n\nif (typeof navigator !== 'undefined' && 'serviceWorker' in navigator) {\n  navigator.serviceWorker.addEventListener('message', (event: MessageEvent) => {\n    if ((event.data as { type?: string } | null)?.type === 'rsc-kit:updated') announce()\n  })\n\n  // A worker that took control after this page loaded is the same news by\n  // another route — it fires when the page was open across a deploy and the\n  // message was posted before this listener existed.\n  navigator.serviceWorker.addEventListener('controllerchange', announce)\n}\n\nexport function isUpdated(): boolean {\n  return updated\n}\n\nexport function subscribeToUpdates(callback: () => void): () => void {\n  listeners.add(callback)\n\n  return () => listeners.delete(callback)\n}\n\n/** The server render's answer. A fresh document is by definition not stale. */\nexport function updatedOnServer(): boolean {\n  return false\n}\n"]}

package/dist/js/useAppUpdate.d.ts

@@ -0,0 +1,4 @@
+export declare function useAppUpdate(): {
+    updated: boolean;
+    reload: () => void;
+};

package/dist/js/useAppUpdate.js

@@ -0,0 +1,29 @@
+"use client";
+/**
+ * Whether a newer build is live, and how to get it.
+ *
+ *     const { updated, reload } = useAppUpdate()
+ *
+ *     if (updated) return <button onClick={reload}>A new version is ready</button>
+ *
+ * Reported rather than acted on. Reloading out from under someone mid-form is
+ * worse than the staleness it fixes, so this package will not do it for you —
+ * what it will do is tell you, which nothing else can, because only the worker
+ * knows a new version activated.
+ */
+import { useSyncExternalStore } from "react";
+import { isUpdated, subscribeToUpdates, updatedOnServer } from "./updateStore";
+export function useAppUpdate() {
+    const updated = useSyncExternalStore(subscribeToUpdates, isUpdated, updatedOnServer);
+    return {
+        updated,
+        // location.reload() rather than a router navigation: the point is to
+        // re-fetch the document and its javascript, and a client navigation
+        // deliberately does neither.
+        reload: () => {
+            if (typeof window !== "undefined")
+                window.location.reload();
+        },
+    };
+}
+//# sourceMappingURL=useAppUpdate.js.map

package/dist/js/useAppUpdate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAppUpdate.js","sourceRoot":"","sources":["../../src/js/useAppUpdate.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAE/E,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,oBAAoB,CAAC,kBAAkB,EAAE,SAAS,EAAE,eAAe,CAAC,CAAC;IAErF,OAAO;QACL,OAAO;QACP,qEAAqE;QACrE,oEAAoE;QACpE,6BAA6B;QAC7B,MAAM,EAAE,GAAG,EAAE;YACX,IAAI,OAAO,MAAM,KAAK,WAAW;gBAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC9D,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["\"use client\";\n\n/**\n * Whether a newer build is live, and how to get it.\n *\n *     const { updated, reload } = useAppUpdate()\n *\n *     if (updated) return <button onClick={reload}>A new version is ready</button>\n *\n * Reported rather than acted on. Reloading out from under someone mid-form is\n * worse than the staleness it fixes, so this package will not do it for you —\n * what it will do is tell you, which nothing else can, because only the worker\n * knows a new version activated.\n */\n\nimport { useSyncExternalStore } from \"react\";\nimport { isUpdated, subscribeToUpdates, updatedOnServer } from \"./updateStore\";\n\nexport function useAppUpdate(): { updated: boolean; reload: () => void } {\n  const updated = useSyncExternalStore(subscribeToUpdates, isUpdated, updatedOnServer);\n\n  return {\n    updated,\n    // location.reload() rather than a router navigation: the point is to\n    // re-fetch the document and its javascript, and a client navigation\n    // deliberately does neither.\n    reload: () => {\n      if (typeof window !== \"undefined\") window.location.reload();\n    },\n  };\n}\n"]}

package/dist/vite.d.ts

@@ -189,7 +189,7 @@ export interface RscKitOptions {
  * Nothing else is touched. An action is a POST and must never be answered from
  * a cache; anything cross-origin is somebody else's to cache.
  */
-export declare const SERVICE_WORKER: (version: string, precache: string[], frozen?: string[]) => string;
+export declare const SERVICE_WORKER: (version: string, precache: string[], frozen?: string[], offlineUrl?: string | null, swExtra?: string | null) => string;
 /**
  * Write the worker beside the assets it caches.
  *

package/dist/vite.js

@@ -566,7 +566,7 @@ function reportAllDynamic() {
  * Nothing else is touched. An action is a POST and must never be answered from
  * a cache; anything cross-origin is somebody else's to cache.
  */
-export const SERVICE_WORKER = (version, precache, frozen = []) => `// GENERATED by rscKit() — do not edit.
+export const SERVICE_WORKER = (version, precache, frozen = [], offlineUrl = null, swExtra = null) => `// GENERATED by rscKit() — do not edit.
 const VERSION = ${JSON.stringify(version)}
 const CACHE = 'rsc-kit-' + VERSION
 const PRECACHE = ${JSON.stringify(precache, null, 2)}
@@ -581,12 +581,48 @@ const PRECACHE = ${JSON.stringify(precache, null, 2)}
 // cache would be wrong in a way the visitor cannot see.
 const FROZEN = new Set(${JSON.stringify(frozen)})
 
+// The page to show when a navigation cannot be answered at all.
+//
+// An ordinary route at /offline, stored at build time like any other — nothing
+// special about the file, only about when it is served. Null when the app has
+// none, and then a navigation with nothing cached fails as it always did.
+//
+// Deliberately NOT the cached root. That was tried: the document IS the page
+// here, so the visitor got the home page's markup under the address they asked
+// for and it did not hydrate — a wrong page pretending to be the right one.
+// This one is about being offline whatever url it appears under, so it is the
+// only page that can honestly stand in for another.
+const OFFLINE_URL = ${JSON.stringify(offlineUrl)}
+${swExtra
+    ? `
+// The app's own worker code — push, notification clicks, background sync.
+//
+// importScripts rather than a bundled import, because this file is evaluated
+// in a worker scope by the browser rather than built: whatever the app wrote is
+// run as it was written, in the same global, so its listeners sit beside the
+// ones below.
+//
+// First, so an app handler for an event this file does not handle is registered
+// before anything here can call respondWith on it.
+self.importScripts(${JSON.stringify(swExtra)})
+`
+    : ''}
+
 self.addEventListener('install', (event) => {
   // The new worker takes over rather than waiting for every tab to close.
   // Safe here because assets are content-hashed: a page already open keeps
   // asking for the names it was built with, and those are still cached under
   // their own version until this activates and sweeps.
-  event.waitUntil(caches.open(CACHE).then((cache) => cache.addAll(PRECACHE)).then(() => self.skipWaiting()))
+  event.waitUntil(
+    caches
+      .open(CACHE)
+      // The offline page is fetched rather than copied from the build output:
+      // it is served by the host out of the prerendered directory, which this
+      // worker cannot see. Added here so it is in the cache before it is
+      // needed, which is the only moment it cannot be fetched.
+      .then((cache) => cache.addAll(OFFLINE_URL ? [...PRECACHE, OFFLINE_URL] : PRECACHE))
+      .then(() => self.skipWaiting()),
+  )
 })
 
 self.addEventListener('activate', (event) => {
@@ -594,10 +630,24 @@ self.addEventListener('activate', (event) => {
     caches
       .keys()
       .then((keys) => Promise.all(keys.filter((k) => k.startsWith('rsc-kit-') && k !== CACHE).map((k) => caches.delete(k))))
-      .then(() => self.clients.claim()),
+      .then(() => self.clients.claim())
+      .then(() => tellTheOpenPages()),
   )
 })
 
+// A page open right now is running the previous build's javascript, and the
+// chunks it has not loaded yet were just swept. It cannot fix that by itself —
+// only a reload gets the new ones — so it is told, and the app decides what to
+// say about it.
+//
+// After the sweep rather than before, so a page acting on this immediately
+// reloads into the new version rather than racing the deletion.
+async function tellTheOpenPages() {
+  const open = await self.clients.matchAll({ type: 'window' })
+
+  for (const page of open) page.postMessage({ type: 'rsc-kit:updated', version: VERSION })
+}
+
 const immutable = (url) => url.pathname.startsWith('/assets/') || /-[A-Za-z0-9_-]{8,}\\.[a-z]+$/.test(url.pathname)
 
 // Whether a response may be kept at all.
@@ -741,12 +791,25 @@ self.addEventListener('fetch', (event) => {
 
         if (hit) return hit
 
-        // Nothing cached for this url and no network to ask. Falling back to
-        // the cached root was worse than failing: the document IS the page
-        // here, so the visitor got the home page's markup under the address
-        // they asked for, and it did not hydrate — a wrong page pretending to
-        // be the right one. Letting it fail says what is true, and a page
-        // already open is unaffected.
+        // Nothing cached for this url and no network to ask.
+        //
+        // Falling back to the cached ROOT was worse than failing: the document
+        // IS the page here, so the visitor got the home page's markup under the
+        // address they asked for, and it did not hydrate — a wrong page
+        // pretending to be the right one.
+        //
+        // An offline page is different, and is the one page that can honestly
+        // stand in for another: it is about being offline, not about the url it
+        // appears under. Navigations only — a payload request answered with a
+        // document would be decoded as one and throw.
+        if (OFFLINE_URL && request.mode === 'navigate') {
+          const page = await caches.match(OFFLINE_URL)
+
+          if (page) return page
+        }
+
+        // Letting it fail says what is true, and a page already open is
+        // unaffected.
         return Response.error()
       }),
   )
@@ -852,9 +915,59 @@ function writeWebManifest(clientDir, options) {
     else
         log(`manifest: ${options.name} is installable`);
 }
-function writeServiceWorker(clientDir, frozen = []) {
+/**
+ * The url a navigation falls back to when nothing else can answer it.
+ *
+ * An ordinary route at /offline, and it has to be one the build STORED — a
+ * page that renders per request cannot be served when there is no request to
+ * be made. So a dynamic /offline is refused as a fallback rather than
+ * precached and found wanting at the one moment it matters, and the build says
+ * which read did it.
+ */
+function offlineFallback(frozen, results) {
+    const found = results.find((r) => r.url === '/offline');
+    if (!found)
+        return null;
+    if (!frozen.includes('/offline')) {
+        // The reason already reads "dynamic — called cookies()", and this sentence
+        // has said "not stored" by the time it gets there, so the prefix would say
+        // it twice with a dash in the middle of both.
+        const why = found.reason?.replace(/^dynamic — /, '') ?? null;
+        log('offline: /offline cannot be the fallback' +
+            (why ? `, because it ${why}` : '') +
+            '. A fallback has to be servable with no network at all.');
+        return null;
+    }
+    return '/offline';
+}
+/**
+ * The app's own service worker code, if it wrote any.
+ *
+ * `src/app/sw.js`, copied next to the generated worker and imported by it. Plain
+ * javascript rather than TypeScript, and that is not an oversight: it is
+ * evaluated by the browser in a worker scope with no build step in front of it,
+ * so what is written is what runs. Calling it .js says so.
+ *
+ * This is the only way to add an event this package does not handle — push,
+ * notificationclick, sync — without giving up everything the generated worker
+ * does. There is no option for it because there is nothing to configure: the
+ * file is there or it is not.
+ */
+function copyServiceWorkerExtra(clientDir) {
+    const source = join(sourceDir, 'app', 'sw.js');
+    if (!existsSync(source))
+        return null;
+    copyFileSync(source, join(clientDir, 'sw-app.js'));
+    return '/sw-app.js';
+}
+function writeServiceWorker(clientDir, frozen = [], offlineUrl = null) {
     if (!existsSync(clientDir))
         return;
+    // Before the walk, so it lands in the precache with everything else. The
+    // worker importScripts it while evaluating, which is the one moment it cannot
+    // go to the network for it — a worker whose import fails does not start, and
+    // then nothing is cached at all.
+    const extra = copyServiceWorkerExtra(clientDir);
     const files = [];
     const walk = (dir, prefix) => {
         for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -872,8 +985,10 @@ function writeServiceWorker(clientDir, frozen = []) {
     walk(clientDir, '');
     const precache = ['/', ...files.map((file) => `/${file}`)].sort();
     const version = createHash('sha256').update(precache.join('\n')).digest('hex').slice(0, 12);
-    writeFileSync(join(clientDir, 'sw.js'), SERVICE_WORKER(version, precache, frozen));
-    log(`offline: ${precache.length} files precached as rsc-kit-${version}`);
+    writeFileSync(join(clientDir, 'sw.js'), SERVICE_WORKER(version, precache, frozen, offlineUrl, extra));
+    log(`offline: ${precache.length} files precached as rsc-kit-${version}` +
+        (offlineUrl ? `, falling back to ${offlineUrl}` : '') +
+        (extra ? ', with app/sw.js' : ''));
 }
 /**
  * The rsc bundle the build just wrote, whatever it decided to call it.
@@ -1008,10 +1123,13 @@ ${legend(counted)}
     // and a 3xx is not `ok`. Saying it here as well means the list means what it
     // says, rather than being a wider list that happens to be filtered later.
     const guarded = new Set(manifest.routes.filter((r) => r.middleware?.length).map((r) => r.component));
-    return results
-        .filter((r) => r.type === 'frozen' && !guarded.has(r.component))
-        .filter((r) => existsSync(join(staticDir, pathKeyOf(r.url) + '.html')))
-        .map((r) => r.url);
+    return {
+        frozen: results
+            .filter((r) => r.type === 'frozen' && !guarded.has(r.component))
+            .filter((r) => existsSync(join(staticDir, pathKeyOf(r.url) + '.html')))
+            .map((r) => r.url),
+        results,
+    };
 }
 /**
  * Weighs the javascript one stored page makes the browser download.
@@ -3781,7 +3899,7 @@ export function rscKit(options = {}) {
             const staticDir = clientOut
                 ? join(dirname(clientOut), 'server', NITRO_STATIC_DIR)
                 : join(outDir, NITRO_STATIC_DIR);
-            const frozen = await prerenderAfterBundles(bundle, staticDir, clientOut ?? publicAssetsDir);
+            const { frozen, results } = await prerenderAfterBundles(bundle, staticDir, clientOut ?? publicAssetsDir);
             // Manifest first. The service worker precaches whatever it finds in this
             // directory, so writing it afterwards leaves it out of the list — and an
             // installed app whose manifest is the one file that needs the network is
@@ -3789,8 +3907,9 @@ export function rscKit(options = {}) {
             copyAppAssets(clientOut ?? publicAssetsDir);
             if (webManifestOptions)
                 writeWebManifest(clientOut ?? publicAssetsDir, webManifestOptions);
-            if (offline)
-                writeServiceWorker(clientOut ?? publicAssetsDir, frozen);
+            if (offline) {
+                writeServiceWorker(clientOut ?? publicAssetsDir, frozen, offlineFallback(frozen, results));
+            }
         },
         configResolved(config) {
             isWatch = config.build?.watch != null;