sveltekit-cache-first 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Isaac Boorman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# SvelteKit Cache First
+
+A small library to make your SvelteKit Web App / PWA local first.
+
+## Setup
+
+```bash
+npm install sveltekit-cache-first
+```
+
+```js
+// src/service-worker.js
+import { version, build, files } from '$service-worker';
+import { setupServiceWorker } from 'sveltekit-cache-first';
+
+setupServiceWorker(self, { version, build, files });
+```
+
+```js
+// src/routes/+layout.svelte
+// Example using toast from svelte-sonner
+import { toast } from 'svelte-sonner';
+import { onUpdate } from 'sveltekit-cache-first';
+
+onMount(() => {
+	onUpdate((accept) => {
+		// Your notification logic here, eg:
+		toast('An update is available', {
+			description: 'Refresh the page to update',
+			action: {
+				label: 'Refresh',
+				onClick: () => accept()
+			}
+		});
+	});
+});
+```
+
+## Config
+
+```js
+// default values
+const options = {
+  cachePageData: false, // Cache _data.json: data returned by load functions
+  ignoredRoutes: ['/api'] // Routes to always fetch fresh for
+}
+
+setupServiceWorker(self, { version, build, files, options });

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { setupServiceWorker } from "./sw.ts";
+import { onUpdate } from "./update.ts";
+export { setupServiceWorker, onUpdate, };

package/dist/index.js

@@ -0,0 +1,4 @@
+// Reexport your entry components here
+import { setupServiceWorker } from "./sw.js";
+import { onUpdate } from "./update.js";
+export { setupServiceWorker, onUpdate, };

package/dist/sw.d.ts

@@ -0,0 +1,11 @@
+type Options = {
+    cachePageData?: boolean;
+    ignoredPaths?: string[];
+};
+export declare function setupServiceWorker(self: ServiceWorkerGlobalScope, { version, build, files, options }: {
+    version: string;
+    build: string[];
+    files: string[];
+    options?: Options;
+}): void;
+export {};

package/dist/sw.js

@@ -0,0 +1,94 @@
+const defaultOptions = {
+    cachePageData: true,
+    ignoredPaths: ['/api'],
+};
+export function setupServiceWorker(self, { version, build, files, options }) {
+    const CACHE = `cache-${version}`;
+    const ASSETS = [...build, ...files];
+    options = options ? { ...defaultOptions, ...options } : defaultOptions;
+    self.addEventListener('install', (event) => {
+        event.waitUntil((async () => {
+            const cache = await caches.open(CACHE);
+            await cache.addAll(ASSETS);
+            // Ensure the SPA shell is cached
+            if (!ASSETS.includes('/')) {
+                await cache.add('/');
+            }
+        })());
+    });
+    self.addEventListener('activate', (event) => {
+        event.waitUntil((async () => {
+            for (const key of await caches.keys()) {
+                if (key !== CACHE) {
+                    await caches.delete(key);
+                }
+            }
+            await self.clients.claim();
+        })());
+    });
+    self.addEventListener('fetch', (event) => {
+        const url = new URL(event.request.url);
+        let skipCache = false;
+        if (event.request.method !== 'GET')
+            skipCache = true;
+        // Never cache SvelteKit page data
+        if (!options.cachePageData && url.pathname.endsWith('/__data.json'))
+            skipCache = true;
+        // Never cache ignored routes
+        if (options.ignoredPaths?.some((route) => url.pathname.startsWith(route)))
+            skipCache = true;
+        if (skipCache)
+            return;
+        event.respondWith(cacheFirstWithSpaFallback(event));
+    });
+    async function cacheFirstWithSpaFallback(event) {
+        const cache = await caches.open(CACHE);
+        const cachedResponse = await cache.match(event.request);
+        const isNavigation = event.request.mode === 'navigate' ||
+            event.request.headers.get('accept')?.includes('text/html');
+        // Start background update
+        const networkUpdate = fetch(event.request)
+            .then((response) => {
+            if (response && response.status === 200) {
+                cache.put(event.request, response.clone());
+            }
+            return response;
+        })
+            .catch(() => undefined);
+        event.waitUntil(networkUpdate);
+        // 1️⃣ Serve cache immediately
+        if (cachedResponse) {
+            return cachedResponse;
+        }
+        // 2️⃣ Try network
+        const networkResponse = await networkUpdate;
+        if (networkResponse) {
+            return networkResponse;
+        }
+        // 3️⃣ Offline navigation → serve SPA shell
+        if (isNavigation) {
+            const shell = await cache.match('/');
+            if (shell) {
+                return shell;
+            }
+        }
+        throw new Error('No cached response and network unavailable');
+    }
+    self.addEventListener('message', (event) => {
+        if (event.data?.type === 'SKLOCALFIRST_GET_VERSION') {
+            console.log('SW received message', event.data, 'ports', event.ports);
+            if (event.data?.type === 'SKLOCALFIRST_GET_VERSION') {
+                const port = event.ports[0];
+                if (port) {
+                    port.postMessage(version);
+                }
+                else {
+                    console.warn('No port received!');
+                }
+            }
+        }
+        if (event.data?.type === 'SKLOCALFIRST_SKIP_WAITING') {
+            self.skipWaiting();
+        }
+    });
+}

package/dist/update.d.ts

@@ -0,0 +1 @@
+export declare function onUpdate(handle: (onAccept: () => void) => void): () => void;

package/dist/update.js

@@ -0,0 +1,53 @@
+function getVersion(worker) {
+    return new Promise((resolve) => {
+        const channel = new MessageChannel();
+        channel.port1.onmessage = (e) => resolve(e.data ?? null);
+        worker.postMessage({ type: 'SKLOCALFIRST_GET_VERSION' }, [channel.port2]);
+    });
+}
+async function checkVersionChanged(worker) {
+    const version = await getVersion(worker);
+    if (!version)
+        return false;
+    const lastPrompted = localStorage.getItem('lastPrompted');
+    if (lastPrompted === version)
+        return false;
+    localStorage.setItem('lastPrompted', version);
+    return true;
+}
+function handleAccept(worker) {
+    worker.postMessage({ type: 'SKLOCALFIRST_SKIP_WAITING' });
+}
+export function onUpdate(handle) {
+    if (!('serviceWorker' in navigator)) {
+        return () => { };
+    }
+    navigator.serviceWorker.getRegistration().then(async (reg) => {
+        if (!reg)
+            return;
+        // 1️⃣ Detect if a waiting SW already exists
+        if (reg.waiting) {
+            const sw = reg.waiting;
+            if (await checkVersionChanged(sw)) {
+                handle(() => handleAccept(sw));
+            }
+        }
+        // 2️⃣ Listen for new SW installations
+        reg.addEventListener('updatefound', () => {
+            const sw = reg.installing;
+            if (!sw)
+                return;
+            sw.addEventListener('statechange', () => {
+                if (sw.state === 'installed' && navigator.serviceWorker.controller) {
+                    // SW installed, new version waiting
+                    handle(() => handleAccept(sw));
+                }
+            });
+        });
+    });
+    // 3️⃣ Reload page when the new SW takes control
+    navigator.serviceWorker.addEventListener('controllerchange', () => {
+        window.location.reload();
+    });
+    return () => { };
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+	"name": "sveltekit-cache-first",
+	"version": "0.0.1",
+	"scripts": {
+		"dev": "vite dev",
+		"build": "vite build && npm run prepack",
+		"preview": "vite preview",
+		"prepare": "svelte-kit sync || echo ''",
+		"prepack": "svelte-kit sync && svelte-package && publint",
+		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+		"lint": "prettier --check . && eslint .",
+		"format": "prettier --write ."
+	},
+	"files": [
+		"dist",
+		"!dist/**/*.test.*",
+		"!dist/**/*.spec.*"
+	],
+	"sideEffects": [
+		"**/*.css"
+	],
+	"svelte": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"svelte": "./dist/index.js"
+		}
+	},
+	"peerDependencies": {
+		"svelte": "^5.0.0",
+		"@sveltejs/kit": "^2.63.0"
+	},
+	"devDependencies": {
+		"@eslint/js": "^10.0.1",
+		"@sveltejs/adapter-auto": "^7.0.1",
+		"@sveltejs/kit": "^2.63.0",
+		"@sveltejs/package": "^2.5.8",
+		"@sveltejs/vite-plugin-svelte": "^7.1.2",
+		"@types/node": "^24",
+		"eslint": "^10.4.1",
+		"eslint-config-prettier": "^10.1.8",
+		"eslint-plugin-svelte": "^3.19.0",
+		"globals": "^17.6.0",
+		"prettier": "^3.8.3",
+		"prettier-plugin-svelte": "^4.1.0",
+		"publint": "^0.3.21",
+		"svelte": "^5.56.1",
+		"svelte-check": "^4.6.0",
+		"typescript": "^6.0.3",
+		"typescript-eslint": "^8.60.1",
+		"vite": "^8.0.16"
+	},
+	"keywords": [
+		"svelte"
+	]
+}