From 816172d67bb856f3935cf1a64fda1ab5bf3442a5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nunzio=20Marf=C3=A8?= <nunzio.marfe@protonmail.com>
Date: Mon, 12 Jan 2026 08:36:03 +0100
Subject: [PATCH] Feature: PWA (#479)

* feat: add PWA support with offline capabilities

- Add web app manifest with icons and theme configuration
- Add service worker with cache-first strategy for static assets
- Add useServiceWorker hook for SW registration
- Add PWA meta tags and Apple-specific tags to index.html
- Update vite.config.ts for optimal asset caching

* Update package-lock.json
---
 index.html                      |   7 ++
 public/manifest.json            |  40 +++++++++++
 public/sw.js                    | 120 ++++++++++++++++++++++++++++++++
 src/hooks/use-service-worker.ts |  71 +++++++++++++++++++
 src/main.tsx                    |   5 ++
 vite.config.ts                  |   7 +-
 6 files changed, 247 insertions(+), 3 deletions(-)
 create mode 100644 public/manifest.json
 create mode 100644 public/sw.js
 create mode 100644 src/hooks/use-service-worker.ts

diff --git a/index.html b/index.html
index b376f7cd..83e38e8e 100644
--- a/index.html
+++ b/index.html
@@ -4,6 +4,13 @@
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/favicon.ico" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <!-- PWA Meta Tags -->
+    <meta name="theme-color" content="#09090b" />
+    <meta name="apple-mobile-web-app-capable" content="yes" />
+    <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
+    <meta name="apple-mobile-web-app-title" content="Termix" />
+    <link rel="apple-touch-icon" href="/icons/512x512.png" />
+    <link rel="manifest" href="/manifest.json" />
     <title>Termix</title>
     <style>
       .hide-scrollbar {
diff --git a/public/manifest.json b/public/manifest.json
new file mode 100644
index 00000000..310fb47e
--- /dev/null
+++ b/public/manifest.json
@@ -0,0 +1,40 @@
+{
+  "name": "Termix",
+  "short_name": "Termix",
+  "description": "A web-based server management platform with SSH terminal, tunneling, and file editing capabilities",
+  "theme_color": "#09090b",
+  "background_color": "#09090b",
+  "display": "standalone",
+  "orientation": "any",
+  "scope": "/",
+  "start_url": "/",
+  "icons": [
+    {
+      "src": "/icons/48x48.png",
+      "sizes": "48x48",
+      "type": "image/png"
+    },
+    {
+      "src": "/icons/64x64.png",
+      "sizes": "64x64",
+      "type": "image/png"
+    },
+    {
+      "src": "/icons/128x128.png",
+      "sizes": "128x128",
+      "type": "image/png"
+    },
+    {
+      "src": "/icons/256x256.png",
+      "sizes": "256x256",
+      "type": "image/png"
+    },
+    {
+      "src": "/icons/512x512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "any maskable"
+    }
+  ],
+  "categories": ["utilities", "developer", "productivity"]
+}
diff --git a/public/sw.js b/public/sw.js
new file mode 100644
index 00000000..e9396271
--- /dev/null
+++ b/public/sw.js
@@ -0,0 +1,120 @@
+/**
+ * Termix Service Worker
+ * Handles caching for offline PWA support
+ */
+
+const CACHE_NAME = "termix-v1";
+const STATIC_ASSETS = [
+  "/",
+  "/index.html",
+  "/manifest.json",
+  "/favicon.ico",
+  "/icons/48x48.png",
+  "/icons/128x128.png",
+  "/icons/256x256.png",
+  "/icons/512x512.png",
+];
+
+// Install event - cache static assets
+self.addEventListener("install", (event) => {
+  event.waitUntil(
+    caches
+      .open(CACHE_NAME)
+      .then((cache) => {
+        console.log("[SW] Caching static assets");
+        return cache.addAll(STATIC_ASSETS);
+      })
+      .then(() => {
+        // Activate immediately without waiting
+        return self.skipWaiting();
+      }),
+  );
+});
+
+// Activate event - clean up old caches
+self.addEventListener("activate", (event) => {
+  event.waitUntil(
+    caches
+      .keys()
+      .then((cacheNames) => {
+        return Promise.all(
+          cacheNames
+            .filter((name) => name !== CACHE_NAME)
+            .map((name) => {
+              console.log("[SW] Deleting old cache:", name);
+              return caches.delete(name);
+            }),
+        );
+      })
+      .then(() => {
+        // Take control of all pages immediately
+        return self.clients.claim();
+      }),
+  );
+});
+
+// Fetch event - serve from cache, fall back to network
+self.addEventListener("fetch", (event) => {
+  const { request } = event;
+  const url = new URL(request.url);
+
+  // Skip non-GET requests
+  if (request.method !== "GET") {
+    return;
+  }
+
+  // Skip API requests - these must be online
+  if (url.pathname.startsWith("/api/") || url.pathname.startsWith("/ws")) {
+    return;
+  }
+
+  // Skip cross-origin requests
+  if (url.origin !== self.location.origin) {
+    return;
+  }
+
+  // For navigation requests (HTML), use network-first
+  if (request.mode === "navigate") {
+    event.respondWith(
+      fetch(request)
+        .then((response) => {
+          // Clone and cache the response
+          const responseClone = response.clone();
+          caches.open(CACHE_NAME).then((cache) => {
+            cache.put(request, responseClone);
+          });
+          return response;
+        })
+        .catch(() => {
+          // Offline: return cached index.html
+          return caches.match("/index.html");
+        }),
+    );
+    return;
+  }
+
+  // For all other assets, use cache-first
+  event.respondWith(
+    caches.match(request).then((cachedResponse) => {
+      if (cachedResponse) {
+        return cachedResponse;
+      }
+
+      // Not in cache, fetch from network
+      return fetch(request).then((response) => {
+        // Don't cache non-successful responses
+        if (!response || response.status !== 200 || response.type !== "basic") {
+          return response;
+        }
+
+        // Clone and cache the response
+        const responseClone = response.clone();
+        caches.open(CACHE_NAME).then((cache) => {
+          cache.put(request, responseClone);
+        });
+
+        return response;
+      });
+    }),
+  );
+});
diff --git a/src/hooks/use-service-worker.ts b/src/hooks/use-service-worker.ts
new file mode 100644
index 00000000..98b122e1
--- /dev/null
+++ b/src/hooks/use-service-worker.ts
@@ -0,0 +1,71 @@
+import { useEffect, useState, useCallback } from "react";
+import { isElectron } from "@/ui/main-axios";
+
+interface ServiceWorkerState {
+    isSupported: boolean;
+    isRegistered: boolean;
+    updateAvailable: boolean;
+}
+
+/**
+ * Hook to manage PWA Service Worker registration.
+ * Only registers in production web environment (not in Electron).
+ */
+export function useServiceWorker(): ServiceWorkerState {
+    const [state, setState] = useState<ServiceWorkerState>({
+        isSupported: false,
+        isRegistered: false,
+        updateAvailable: false,
+    });
+
+    const handleUpdateFound = useCallback(
+        (registration: ServiceWorkerRegistration) => {
+            const newWorker = registration.installing;
+            if (!newWorker) return;
+
+            newWorker.addEventListener("statechange", () => {
+                if (
+                    newWorker.state === "installed" &&
+                    navigator.serviceWorker.controller
+                ) {
+                    setState((prev) => ({ ...prev, updateAvailable: true }));
+                    console.log("[SW] Update available");
+                }
+            });
+        },
+        [],
+    );
+
+    useEffect(() => {
+        const isSupported =
+            "serviceWorker" in navigator && !isElectron() && import.meta.env.PROD;
+
+        setState((prev) => ({ ...prev, isSupported }));
+
+        if (!isSupported) return;
+
+        const registerSW = async () => {
+            try {
+                const registration = await navigator.serviceWorker.register("/sw.js");
+                console.log("[SW] Registered:", registration.scope);
+
+                setState((prev) => ({ ...prev, isRegistered: true }));
+
+                registration.addEventListener("updatefound", () =>
+                    handleUpdateFound(registration),
+                );
+            } catch (error) {
+                console.error("[SW] Registration failed:", error);
+            }
+        };
+
+        if (document.readyState === "complete") {
+            registerSW();
+        } else {
+            window.addEventListener("load", registerSW);
+            return () => window.removeEventListener("load", registerSW);
+        }
+    }, [handleUpdateFound]);
+
+    return state;
+}
diff --git a/src/main.tsx b/src/main.tsx
index 0202bb43..19a6c8c9 100644
--- a/src/main.tsx
+++ b/src/main.tsx
@@ -8,6 +8,7 @@ import { ThemeProvider } from "@/components/theme-provider";
 import { ElectronVersionCheck } from "@/ui/desktop/user/ElectronVersionCheck.tsx";
 import "./i18n/i18n";
 import { isElectron } from "./ui/main-axios.ts";
+import { useServiceWorker } from "@/hooks/use-service-worker";
 
 function useWindowWidth() {
   const [width, setWidth] = useState(window.innerWidth);
@@ -58,6 +59,9 @@ function RootApp() {
   const isMobile = width < 768;
   const [showVersionCheck, setShowVersionCheck] = useState(true);
 
+  // PWA Service Worker registration (production web only)
+  useServiceWorker();
+
   const userAgent =
     navigator.userAgent || navigator.vendor || (window as any).opera || "";
   const isTermixMobile = /Termix-Mobile/.test(userAgent);
@@ -114,3 +118,4 @@ createRoot(document.getElementById("root")!).render(
     </ThemeProvider>
   </StrictMode>,
 );
+
diff --git a/vite.config.ts b/vite.config.ts
index c0fd1337..574a177f 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -20,6 +20,7 @@ export default defineConfig({
   base: "./",
   build: {
     sourcemap: false,
+    assetsInlineLimit: 0,
     rollupOptions: {
       output: {
         manualChunks: {
@@ -35,9 +36,9 @@ export default defineConfig({
   server: {
     https: useHTTPS
       ? {
-          cert: fs.readFileSync(sslCertPath),
-          key: fs.readFileSync(sslKeyPath),
-        }
+        cert: fs.readFileSync(sslCertPath),
+        key: fs.readFileSync(sslKeyPath),
+      }
       : false,
     port: 5173,
     host: "localhost",