Merge pull request #1276 from RicoUHD/white-screen-of-death

mtthidoteu · web-flow · commit a6f17df7b283 · 2026-05-30T13:52:15.000+02:00
Resolve WSOD by restructuring asset management and cache strategies
diff --git a/.dockerignore b/.dockerignore
@@ -46,6 +46,8 @@ app/static/css/main.css
 app/static/js/sortable.min.js
 app/static/js/tiny-mde.min.js
 app/static/css/tiny-mde.min.css
+app/static/js/vendor/
+app/static/css/vendor/
 
 # Lock files generated by CI before container build
 
diff --git a/.gitignore b/.gitignore
@@ -6,6 +6,13 @@
 # compiled tailwindcss file
 app/static/css/main.css
 
+# Portable development tools
+.tools/
+
+# Compiled static vendor assets
+app/static/js/vendor/
+app/static/css/vendor/
+
 CLAUDE.md
 .python-version
 
diff --git a/Dockerfile b/Dockerfile
@@ -41,7 +41,7 @@ RUN --mount=type=cache,target=/root/.cache/uv \
 RUN uv run --frozen --no-dev pybabel compile --use-fuzzy -d app/translations
 
 # Ensure static directories exist and build static assets
-RUN mkdir -p app/static/js app/static/css && npm --prefix app/static/ run build
+RUN mkdir -p app/static/js app/static/css && DOCKER_BUILD=true npm --prefix app/static/ run build
 
 # ─── Stage 3: Runtime ─────────────────────────────────────────────────────
 FROM ghcr.io/astral-sh/uv:python3.13-alpine
diff --git a/app/__init__.py b/app/__init__.py
@@ -68,10 +68,11 @@ def create_app(config_object=DevelopmentConfig):
     # Step 5: Setup context processors and filters
     if show_startup:
         logger.step("Configuring request processing", "⚙️")
-    from .context_processors import inject_plus_features, inject_server_name
+    from .context_processors import inject_plus_features, inject_server_name, inject_app_version
 
     app.context_processor(inject_server_name)
     app.context_processor(inject_plus_features)
+    app.context_processor(inject_app_version)
     register_error_handlers(app)
 
     # Register custom Jinja filters
diff --git a/app/context_processors.py b/app/context_processors.py
@@ -1,3 +1,4 @@
+import os
 from app.extensions import db
 from app.models import Settings
 
@@ -30,3 +31,8 @@ def inject_plus_features():
         is_plus_enabled = False
 
     return {"is_plus_enabled": is_plus_enabled}
+
+
+def inject_app_version():
+    """Inject current app version into template context for cache busting."""
+    return {"app_version": os.getenv("APP_VERSION", "dev")}
diff --git a/app/static/copy-assets.js b/app/static/copy-assets.js
@@ -0,0 +1,54 @@
+const fs = require('fs');
+const path = require('path');
+
+const assets = [
+    // Original assets
+    { src: 'node_modules/sortablejs/Sortable.min.js', dest: 'js/sortable.min.js' },
+    { src: 'node_modules/tiny-markdown-editor/dist/tiny-mde.min.js', dest: 'js/tiny-mde.min.js' },
+    { src: 'node_modules/tiny-markdown-editor/dist/tiny-mde.min.css', dest: 'css/tiny-mde.min.css' },
+
+    // Safe Vendor assets (to fix the White Screen of Death / WAF node_modules blocks)
+    { src: 'node_modules/alpinejs/dist/cdn.min.js', dest: 'js/vendor/alpine.min.js' },
+    { src: 'node_modules/@alpinejs/collapse/dist/cdn.min.js', dest: 'js/vendor/alpine-collapse.min.js' },
+    { src: 'node_modules/flowbite/dist/flowbite.min.js', dest: 'js/vendor/flowbite.min.js' },
+    { src: 'node_modules/htmx.org/dist/htmx.min.js', dest: 'js/vendor/htmx.min.js' },
+    { src: 'node_modules/htmx-ext-preload/dist/preload.min.js', dest: 'js/vendor/htmx-preload.min.js' },
+    { src: 'node_modules/animate.css/animate.min.css', dest: 'css/vendor/animate.min.css' },
+    { src: 'node_modules/bowser/bundled.js', dest: 'js/vendor/bowser.min.js' },
+    { src: 'node_modules/inapp-spy/dist/index.global.js', dest: 'js/vendor/inapp-spy.min.js' }
+];
+
+const isProduction = process.env.NODE_ENV === 'production' || process.env.DOCKER_BUILD === 'true';
+
+console.log('📦 Starting cross-platform asset copy...');
+
+assets.forEach(asset => {
+    const srcPath = path.resolve(__dirname, asset.src);
+    const destPath = path.resolve(__dirname, asset.dest);
+
+    if (!fs.existsSync(srcPath)) {
+        if (isProduction) {
+            console.error(`❌ CRITICAL: Source file missing for production build: ${asset.src}`);
+            process.exit(1); // Fails the build pipeline safely
+        } else {
+            console.warn(`⚠️ Warning: Source file not found: ${asset.src}. Skipping in dev mode.`);
+            return;
+        }
+    }
+
+    // Ensure destination directory exists
+    const destDir = path.dirname(destPath);
+    if (!fs.existsSync(destDir)) {
+        fs.mkdirSync(destDir, { recursive: true });
+    }
+
+    try {
+        fs.copyFileSync(srcPath, destPath);
+        console.log(`✓ Copied ${asset.src} -> ${asset.dest}`);
+    } catch (err) {
+        console.error(`❌ Failed to copy ${asset.src}:`, err);
+        process.exit(1);
+    }
+});
+
+console.log('✨ All assets copied successfully!');
diff --git a/app/static/js/in-app-escape.js b/app/static/js/in-app-escape.js
@@ -12,7 +12,7 @@
   window.wizarrInAppEscapeLoaded = true;
 
   // Import dependencies from node_modules
-  const Bowser = window.Bowser;
+  const Bowser = window.Bowser || window.bowser;
   const InAppSpy = window.InAppSpy;
 
   if (!Bowser || !InAppSpy) {
diff --git a/app/static/js/pwa-registration.js b/app/static/js/pwa-registration.js
@@ -11,9 +11,25 @@
   // Service Worker Registration
   if ('serviceWorker' in navigator) {
     window.addEventListener('load', function() {
-      navigator.serviceWorker.register('/static/sw.js')
+      // updateViaCache: 'none' ensures the browser always fetches sw.js from the
+      // server instead of the HTTP cache, so service worker updates are detected
+      // immediately after deployment.
+      navigator.serviceWorker.register('/static/sw.js', { updateViaCache: 'none' })
         .then(function(registration) {
           console.log('ServiceWorker registration successful with scope: ', registration.scope);
+
+          // Check for service worker updates every hour
+          setInterval(function() { registration.update(); }, 60 * 60 * 1000);
+
+          // Listen for a new service worker becoming available
+          registration.addEventListener('updatefound', function() {
+            var newWorker = registration.installing;
+            newWorker.addEventListener('statechange', function() {
+              if (newWorker.state === 'activated') {
+                console.log('New Wizarr version activated');
+              }
+            });
+          });
         })
         .catch(function(err) {
           console.log('ServiceWorker registration failed: ', err);
diff --git a/app/static/js/tiny-mde.min.js b/app/static/js/tiny-mde.min.js
diff --git a/app/static/package.json b/app/static/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "build:css": "npx @tailwindcss/cli -i src/style.css -o css/main.css",
     "watch:css": "npx @tailwindcss/cli -i src/style.css -o css/main.css --watch",
-    "build:js": "cp node_modules/sortablejs/Sortable.min.js js/sortable.min.js && cp node_modules/tiny-markdown-editor/dist/tiny-mde.min.js js/tiny-mde.min.js && cp node_modules/tiny-markdown-editor/dist/tiny-mde.min.css css/tiny-mde.min.css",
+    "build:js": "node copy-assets.js",
     "build": "npm run build:css && npm run build:js"
   },
   "author": "",
diff --git a/app/static/sw.js b/app/static/sw.js
@@ -1,57 +1,93 @@
-const CACHE_NAME = 'wizarr-v1';
+const CACHE_NAME = 'wizarr-v2';
 const urlsToCache = [
-  '/',
   '/static/css/main.css',
   '/static/js/dark-mode-switch.js',
   '/static/favicon.ico',
   '/static/wizarr-logo.png',
-  '/static/node_modules/htmx.org/dist/htmx.min.js',
-  '/static/node_modules/alpinejs/dist/cdn.min.js',
-  '/static/node_modules/flowbite/dist/flowbite.min.js',
-  '/static/node_modules/@alpinejs/collapse/dist/cdn.min.js'
+  '/static/js/vendor/htmx.min.js',
+  '/static/js/vendor/alpine.min.js',
+  '/static/js/vendor/flowbite.min.js',
+  '/static/js/vendor/alpine-collapse.min.js'
 ];
 
-// Install event - cache resources
+// Install event - cache resources and activate immediately
 self.addEventListener('install', (event) => {
+  // Skip waiting so the new service worker activates immediately,
+  // ensuring users with stale caches get the fix without closing all tabs.
+  self.skipWaiting();
   event.waitUntil(
     caches.open(CACHE_NAME)
       .then((cache) => {
-        console.log('Opened cache');
+        console.log('Opened cache:', CACHE_NAME);
         return cache.addAll(urlsToCache);
       })
   );
 });
 
-// Fetch event - serve from cache, fallback to network
+// Fetch event - network-first for HTML pages, stale-while-revalidate for static assets
 self.addEventListener('fetch', (event) => {
+  // Only handle GET requests
+  if (event.request.method !== 'GET') {
+    return;
+  }
+
+  // Network-first for HTML page navigation to ensure dynamic Flask backend state works
+  if (event.request.mode === 'navigate' || (event.request.headers.get('accept') && event.request.headers.get('accept').includes('text/html'))) {
+    event.respondWith(
+      fetch(event.request)
+        .catch(() => {
+          return caches.match(event.request);
+        })
+    );
+    return;
+  }
+
+  // Stale-while-revalidate for static assets:
+  // Serve from cache immediately for speed, but fetch a fresh copy in the
+  // background so the next load always has the latest version.
   event.respondWith(
-    caches.match(event.request)
-      .then((response) => {
-        // Cache hit - return response
-        if (response) {
-          return response;
+    caches.open(CACHE_NAME).then((cache) => {
+      return cache.match(event.request).then((cachedResponse) => {
+        const fetchPromise = fetch(event.request).then((networkResponse) => {
+          // Only cache successful responses from our own origin
+          if (networkResponse && networkResponse.status === 200 && networkResponse.type === 'basic') {
+            cache.put(event.request, networkResponse.clone());
+          }
+          return networkResponse;
+        }).catch(() => {
+          // Network failed, cachedResponse (if any) is already being returned
+        });
+        if (cachedResponse) {
+          // Keep the service worker alive to complete the background fetch and cache update
+          event.waitUntil(fetchPromise);
+          return cachedResponse;
         }
-        return fetch(event.request);
-      })
+        return fetchPromise;
+      });
+    })
   );
 });
 
-// Activate event - clean up old caches
+// Activate event - clean up old caches and claim all open clients immediately
 self.addEventListener('activate', (event) => {
   event.waitUntil(
     caches.keys().then((cacheNames) => {
       return Promise.all(
         cacheNames.map((cacheName) => {
           if (cacheName !== CACHE_NAME) {
+            console.log('Deleting old cache:', cacheName);
             return caches.delete(cacheName);
           }
         })
       );
     })
+    // Claim all open clients so the new service worker takes control immediately,
+    // without requiring a page reload.
+    .then(() => self.clients.claim())
   );
 });
 
-// Handle background sync and push notifications (optional)
+// Handle background sync and push notifications
 self.addEventListener('sync', (event) => {
   console.log('Background sync event:', event);
 });
diff --git a/app/templates/base.html b/app/templates/base.html
@@ -3,13 +3,13 @@
   <head>
     <meta charset="utf-8">
     <link rel="stylesheet"
-          href="{{ url_for('static',filename='css/main.css') }}" />
+          href="{{ url_for('static', filename='css/main.css', v=app_version) }}" />
     <link rel="stylesheet"
-          href="{{ url_for('static', filename='css/tiny-mde.min.css') }}" />
+          href="{{ url_for('static', filename='css/tiny-mde.min.css', v=app_version) }}" />
     <link rel="stylesheet"
-          href="{{ url_for ('static', filename='node_modules/animate.css/animate.min.css') }}">
-    <script src="{{ url_for('static', filename='node_modules/htmx.org/dist/htmx.min.js') }}"></script>
-    <script src="{{ url_for('static', filename='node_modules/htmx-ext-preload/dist/preload.min.js') }}"></script>
+          href="{{ url_for('static', filename='css/vendor/animate.min.css', v=app_version) }}">
+    <script src="{{ url_for('static', filename='js/vendor/htmx.min.js', v=app_version) }}"></script>
+    <script src="{{ url_for('static', filename='js/vendor/htmx-preload.min.js', v=app_version) }}"></script>
     <link rel="icon"
           type="image/x-icon"
           href="{{ url_for('static', filename='favicon.ico') }}">
@@ -124,20 +124,18 @@
   <body class="bg-gray-50 dark:bg-gray-900">
     {% block main %}
     {% endblock main %}
-    <link rel="stylesheet"
-          href="{{ url_for('static',filename='css/main.css') }}" />
-    <script src="{{url_for('static', filename='node_modules/alpinejs/dist/cdn.min.js')}}"></script>
-    <script src="{{ url_for('static', filename='node_modules/flowbite/dist/flowbite.min.js') }}"></script>
-    <script src="{{url_for('static', filename='node_modules/@alpinejs/collapse/dist/cdn.min.js')}}"></script>
-    <script src="{{url_for('static', filename='js/dark-mode-switch.js')}}"></script>
-    <script src="{{ url_for('static', filename='js/tiny-mde.min.js') }}"></script>
-    <script src="{{ url_for('static', filename='js/init-tinymde.js') }}"></script>
-    <script src="{{ url_for('static', filename='js/sortable.min.js') }}"></script>
-    <script src="{{ url_for('static', filename='js/wizard-steps.js') }}"></script>
-    <script src="{{ url_for('static', filename='js/pwa-registration.js') }}"></script>
+    <script src="{{ url_for('static', filename='js/vendor/alpine-collapse.min.js', v=app_version) }}"></script>
+    <script src="{{ url_for('static', filename='js/vendor/alpine.min.js', v=app_version) }}"></script>
+    <script src="{{ url_for('static', filename='js/vendor/flowbite.min.js', v=app_version) }}"></script>
+    <script src="{{ url_for('static', filename='js/dark-mode-switch.js', v=app_version) }}"></script>
+    <script src="{{ url_for('static', filename='js/tiny-mde.min.js', v=app_version) }}"></script>
+    <script src="{{ url_for('static', filename='js/init-tinymde.js', v=app_version) }}"></script>
+    <script src="{{ url_for('static', filename='js/sortable.min.js', v=app_version) }}"></script>
+    <script src="{{ url_for('static', filename='js/wizard-steps.js', v=app_version) }}"></script>
+    <script src="{{ url_for('static', filename='js/pwa-registration.js', v=app_version) }}"></script>
     <!-- In-app browser escape -->
-    <script src="{{ url_for('static', filename='node_modules/bowser/bundled.js') }}"></script>
-    <script src="{{ url_for('static', filename='node_modules/inapp-spy/dist/index.global.js') }}"></script>
-    <script src="{{ url_for('static', filename='js/in-app-escape.js') }}"></script>
+    <script src="{{ url_for('static', filename='js/vendor/bowser.min.js', v=app_version) }}"></script>
+    <script src="{{ url_for('static', filename='js/vendor/inapp-spy.min.js', v=app_version) }}"></script>
+    <script src="{{ url_for('static', filename='js/in-app-escape.js', v=app_version) }}"></script>
   </body>
 </html>
diff --git a/app/templates/user-plex-login.html b/app/templates/user-plex-login.html
@@ -274,7 +274,7 @@ <h2 class="text-2xl font-bold text-white mb-2">{{ _("Enter Code to Continue") }}
           }
       }
   </style>
-  <script src="https://unpkg.com/bowser@2.7.0/es5.js"></script> <!-- needed for plexHeaders -->
+  <script src="{{ url_for('static', filename='js/vendor/bowser.min.js', v=app_version) }}"></script> <!-- needed for plexHeaders -->
   <script>
       // Load movie posters for flowing grid background with progressive loading
       async function loadCinemaPosters() {
