Commit 7: PWA (Manifest, Service Worker, Icons, Offline-Grundfunktion)

2026-07-19 03:07:21 +02:00
parent 2f31996bbb
commit 7ae5a353cd
13 changed files with 2918 additions and 10 deletions
--- a/README.md
+++ b/README.md
@@ -77,11 +77,13 @@ Dieser erste Commit liefert ein lauffähiges Grundgerüst:
  Drag & Drop), Scanner (FritzBox-Trigger + Sammel-Scan), Logs (Scan-Historie),
  Einstellungen (Live-Systeminfo + Theme), Plugins (ehrlicher Hinweis auf
  zukünftigen Commit)
+- ✅ PWA: installierbar (Manifest + Icons für Android/iOS/Desktop), Service
+  Worker mit App-Shell-Precaching, `/api/*` läuft offline über den letzten
+  Cache-Stand (NetworkFirst, 3s-Timeout)

 Noch **nicht** enthalten (folgt in den nächsten Commits):

 - Plugin-System (Scanner registrieren, Geräte importieren, Menüs erweitern, Icons)
- PWA-Manifest / Offline-Grundfunktion
 - shadcn/ui, React Hook Form (aktuell einfache kontrollierte Formulare)

 ### Umgebungsvariablen (.env)
--- a/apps/frontend/index.html
+++ b/apps/frontend/index.html
@@ -4,6 +4,9 @@
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="theme-color" content="#0a0a0a" />
+    <meta name="description" content="Schneller, minimalistischer Homelab-Launcher" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
    <title>LaunchPad</title>
  </head>
  <body class="bg-white dark:bg-black">
@@ -11,3 +14,4 @@
    <script type="module" src="/src/main.tsx"></script>
  </body>
 </html>
+
--- a/apps/frontend/nginx.conf
+++ b/apps/frontend/nginx.conf
@@ -19,6 +19,19 @@ server {
        proxy_set_header X-Forwarded-Proto $scheme;
    }

+    # Service Worker und Manifest dürfen nicht langfristig gecacht werden,
+    # sonst bekommen installierte PWA-Nutzer nie ein Update mit.
+    location = /sw.js {
+        add_header Cache-Control "no-cache";
+        try_files $uri =404;
+    }
+
+    location = /manifest.webmanifest {
+        add_header Cache-Control "no-cache";
+        default_type application/manifest+json;
+        try_files $uri =404;
+    }
+
    location ~* \.(?:css|js|svg|png|jpg|jpeg|gif|ico|woff2?)$ {
        expires 7d;
        add_header Cache-Control "public, max-age=604800, immutable";
--- a/apps/frontend/package.json
+++ b/apps/frontend/package.json
@@ -25,6 +25,7 @@
    "postcss": "^8.4.41",
    "tailwindcss": "^3.4.10",
    "typescript": "^5.5.4",
-    "vite": "^5.4.1"
+    "vite": "^5.4.1",
+    "vite-plugin-pwa": "^0.20.5"
  }
 }
--- a/apps/frontend/public/apple-touch-icon.png
+++ b/apps/frontend/public/apple-touch-icon.png
--- a/apps/frontend/public/favicon.svg
+++ b/apps/frontend/public/favicon.svg
@@ -0,0 +1,5 @@
+<svg width="512" height="512" viewBox="0 0 512 512" xmlns="http://www.w3.org/2000/svg">
+  <rect width="512" height="512" rx="112" fill="#0a0a0a"/>
+  <path d="M 200 140 L 200 372 L 372 256 Z" fill="#ffffff"/>
+  <circle cx="150" cy="256" r="26" fill="#ffffff"/>
+</svg>
--- a/apps/frontend/public/icons/icon-192.png
+++ b/apps/frontend/public/icons/icon-192.png
--- a/apps/frontend/public/icons/icon-512.png
+++ b/apps/frontend/public/icons/icon-512.png
--- a/apps/frontend/public/icons/icon-maskable-192.png
+++ b/apps/frontend/public/icons/icon-maskable-192.png
--- a/apps/frontend/public/icons/icon-maskable-512.png
+++ b/apps/frontend/public/icons/icon-maskable-512.png
--- a/apps/frontend/vite.config.ts
+++ b/apps/frontend/vite.config.ts
@@ -1,8 +1,59 @@
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
+import { VitePWA } from "vite-plugin-pwa";

 export default defineConfig({
-  plugins: [react()],
+  plugins: [
+    react(),
+    VitePWA({
+      registerType: "autoUpdate",
+      includeAssets: ["favicon.svg", "apple-touch-icon.png"],
+      manifest: {
+        name: "LaunchPad",
+        short_name: "LaunchPad",
+        description: "Schneller, minimalistischer Homelab-Launcher",
+        lang: "de",
+        theme_color: "#0a0a0a",
+        background_color: "#0a0a0a",
+        display: "standalone",
+        start_url: "/",
+        icons: [
+          { src: "/icons/icon-192.png", sizes: "192x192", type: "image/png" },
+          { src: "/icons/icon-512.png", sizes: "512x512", type: "image/png" },
+          {
+            src: "/icons/icon-maskable-192.png",
+            sizes: "192x192",
+            type: "image/png",
+            purpose: "maskable",
+          },
+          {
+            src: "/icons/icon-maskable-512.png",
+            sizes: "512x512",
+            type: "image/png",
+            purpose: "maskable",
+          },
+        ],
+      },
+      workbox: {
+        // Zeigt beim Offline-Öffnen weiterhin die (gecachte) App-Shell an.
+        navigateFallback: "/index.html",
+        runtimeCaching: [
+          {
+            // Zuletzt geladene Geräte/Dienste/Kategorien bleiben offline verfügbar
+            // (NetworkFirst: frische Daten, wenn erreichbar, sonst letzter Cache-Stand).
+            urlPattern: ({ url }: { url: URL }) => url.pathname.startsWith("/api/"),
+            handler: "NetworkFirst",
+            options: {
+              cacheName: "launchpad-api-cache",
+              networkTimeoutSeconds: 3,
+              cacheableResponse: { statuses: [0, 200] },
+              expiration: { maxEntries: 100, maxAgeSeconds: 60 * 60 * 24 },
+            },
+          },
+        ],
+      },
+    }),
+  ],
  server: {
    host: true,
    port: 5173,
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -72,9 +72,25 @@ Grundgerüst aus Commit 1.
 > Verifikation stützt sich auf erfolgreichen TypeScript-/Vite-Build und
 > Codeprüfung.

-## Commit 7 — PWA
+## ✅ Commit 7 — PWA (erledigt)

- Manifest, Service Worker, Offline-Grundfunktion, Installierbarkeit
+- `vite-plugin-pwa` mit generiertem Manifest (`manifest.webmanifest`) und
+  Service Worker (Workbox, `generateSW`-Modus)
+- Echte Icons (192/512, jeweils normal + maskable, `apple-touch-icon.png`,
+  `favicon.svg`) unter `apps/frontend/public/`
+- App-Shell wird precached; `/api/*` läuft über `NetworkFirst` mit 3s-Timeout
+  und Cache-Fallback – Suche funktioniert damit auch offline mit dem zuletzt
+  geladenen Datenstand
+- `nginx.conf`: `sw.js`/`manifest.webmanifest` explizit von der 7-Tage-Cache-Regel
+  ausgenommen (sonst kommen Updates bei installierten Nutzern nie an), korrekter
+  MIME-Type für das Manifest gesetzt
+
+> Verifiziert: Manifest gegen Installierbarkeits-Anforderungen geprüft (512er-Icon,
+> maskable Icon, alle Pflichtfelder vorhanden), alle Assets über einen echten
+> HTTP-Server abgerufen (200 OK, korrekte Content-Types), generierter Service-Worker-
+> Code inspiziert (Precache-Liste + NetworkFirst-Route bestätigt), vollständige
+> Docker-Build-Simulation durchlaufen. Die tatsächliche "Zum Homescreen hinzufügen"-
+> Installation konnte mangels Browser in dieser Umgebung nicht getestet werden.

 ## Commit 8 — Plugin-System

--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml