From 2b298670938ccf83e1418735cff5b1e0163bb4fc Mon Sep 17 00:00:00 2001
From: Samir Boulahtit <samir.boulahtit@wizard.lu>
Date: Fri, 27 Feb 2026 11:22:29 +0100
Subject: [PATCH] =?UTF-8?q?fix:=20Alpine.js=20defer=20race=20condition=20?=
 =?UTF-8?q?=E2=80=94=20blank=20pages=20on=20first=20load?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Dynamic script creation (document.createElement) ignores the defer
attribute per HTML spec — scripts are async regardless. Alpine.js CDN
loaded fast and auto-initialized before page scripts had executed,
causing ReferenceError for x-data functions (adminStores, dark,
isSideMenuOpen, etc.) and blank pages.

Fix: Replace dynamic script creation with static <script defer> tags
and move extra_scripts block BEFORE Alpine.js in all 4 base templates
(admin, store, merchant, storefront). Alpine.js is now always the last
deferred script, ensuring all page functions are defined before it
auto-initializes.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 app/templates/admin/base.html      | 31 ++++++++----------------------
 app/templates/merchant/base.html   | 25 +++++-------------------
 app/templates/store/base.html      | 25 +++++-------------------
 app/templates/storefront/base.html | 25 +++++-------------------
 4 files changed, 23 insertions(+), 83 deletions(-)

diff --git a/app/templates/admin/base.html b/app/templates/admin/base.html
index e8077347..871347fe 100644
--- a/app/templates/admin/base.html
+++ b/app/templates/admin/base.html
@@ -144,35 +144,20 @@
     <!-- 8a. Alpine.js Collapse Plugin (must load before Alpine) -->
     <script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/collapse@3.13.3/dist/cdn.min.js"></script>
 
-    <!-- 8b. Alpine.js v3 with CDN fallback (with defer) -->
-    <script>
-    (function() {
-        var script = document.createElement('script');
-        script.defer = true;
-        script.src = 'https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js';
-
-        script.onerror = function() {
-            console.warn('Alpine.js CDN failed, loading local copy...');
-            var fallbackScript = document.createElement('script');
-            fallbackScript.defer = true;
-            fallbackScript.src = '{{ url_for("static", path="shared/js/lib/alpine.min.js") }}';
-            document.head.appendChild(fallbackScript);
-        };
-
-        document.head.appendChild(script);
-    })();
-    </script>
-
-    <!-- 9. OPTIONAL: Chart.js with CDN fallback (loaded on demand via block) -->
+    <!-- 8b. OPTIONAL: Chart.js with CDN fallback (loaded on demand via block) -->
     {% block chartjs_script %}{% endblock %}
 
-    <!-- 10. OPTIONAL: Flatpickr with CDN fallback (loaded on demand via block) -->
+    <!-- 8c. OPTIONAL: Flatpickr with CDN fallback (loaded on demand via block) -->
     {% block flatpickr_script %}{% endblock %}
 
-    <!-- 11. OPTIONAL: Quill with CDN fallback (loaded on demand via block) -->
+    <!-- 8d. OPTIONAL: Quill with CDN fallback (loaded on demand via block) -->
     {% block quill_script %}{% endblock %}
 
-    <!-- 12. LAST: Page-specific scripts -->
+    <!-- 9. Page-specific scripts (MUST load before Alpine.js) -->
     {% block extra_scripts %}{% endblock %}
+
+    <!-- 10. LAST: Alpine.js v3 (must be last defer script — auto-initializes on load) -->
+    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js"
+            onerror="var s=document.createElement('script');s.defer=true;s.src='{{ url_for('static', path='shared/js/lib/alpine.min.js') }}';document.head.appendChild(s);"></script>
 </body>
 </html>
diff --git a/app/templates/merchant/base.html b/app/templates/merchant/base.html
index 17555e5c..88734252 100644
--- a/app/templates/merchant/base.html
+++ b/app/templates/merchant/base.html
@@ -71,26 +71,11 @@
     <!-- 5. FIFTH: API Client (depends on Utils) -->
     <script defer src="{{ url_for('static', path='shared/js/api-client.js') }}"></script>
 
-    <!-- 6. SIXTH: Alpine.js v3 with CDN fallback (with defer) -->
-    <script>
-    (function() {
-        var script = document.createElement('script');
-        script.defer = true;
-        script.src = 'https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js';
-
-        script.onerror = function() {
-            console.warn('Alpine.js CDN failed, loading local copy...');
-            var fallbackScript = document.createElement('script');
-            fallbackScript.defer = true;
-            fallbackScript.src = '{{ url_for("static", path="shared/js/lib/alpine.min.js") }}';
-            document.head.appendChild(fallbackScript);
-        };
-
-        document.head.appendChild(script);
-    })();
-    </script>
-
-    <!-- 7. LAST: Page-specific scripts -->
+    <!-- 6. Page-specific scripts (MUST load before Alpine.js) -->
     {% block extra_scripts %}{% endblock %}
+
+    <!-- 7. LAST: Alpine.js v3 (must be last defer script — auto-initializes on load) -->
+    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js"
+            onerror="var s=document.createElement('script');s.defer=true;s.src='{{ url_for('static', path='shared/js/lib/alpine.min.js') }}';document.head.appendChild(s);"></script>
 </body>
 </html>
diff --git a/app/templates/store/base.html b/app/templates/store/base.html
index 76a17699..b671c1df 100644
--- a/app/templates/store/base.html
+++ b/app/templates/store/base.html
@@ -94,26 +94,11 @@
     <!-- 7. SEVENTH: Upgrade Prompts (depends on API Client, registers with Alpine) -->
     <script defer src="{{ url_for('billing_static', path='shared/js/upgrade-prompts.js') }}"></script>
 
-    <!-- 8. EIGHTH: Alpine.js v3 with CDN fallback (with defer) -->
-    <script>
-    (function() {
-        var script = document.createElement('script');
-        script.defer = true;
-        script.src = 'https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js';
-
-        script.onerror = function() {
-            console.warn('Alpine.js CDN failed, loading local copy...');
-            var fallbackScript = document.createElement('script');
-            fallbackScript.defer = true;
-            fallbackScript.src = '{{ url_for("static", path="shared/js/lib/alpine.min.js") }}';
-            document.head.appendChild(fallbackScript);
-        };
-
-        document.head.appendChild(script);
-    })();
-    </script>
-
-    <!-- 9. LAST: Page-specific scripts -->
+    <!-- 8. Page-specific scripts (MUST load before Alpine.js) -->
     {% block extra_scripts %}{% endblock %}
+
+    <!-- 9. LAST: Alpine.js v3 (must be last defer script — auto-initializes on load) -->
+    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js"
+            onerror="var s=document.createElement('script');s.defer=true;s.src='{{ url_for('static', path='shared/js/lib/alpine.min.js') }}';document.head.appendChild(s);"></script>
 </body>
 </html>
diff --git a/app/templates/storefront/base.html b/app/templates/storefront/base.html
index c55e8b40..7e2da460 100644
--- a/app/templates/storefront/base.html
+++ b/app/templates/storefront/base.html
@@ -380,28 +380,13 @@
     {# 6. API Client #}
     <script defer src="{{ url_for('static', path='shared/js/api-client.js') }}"></script>
 
-    {# 7. Alpine.js with CDN fallback (deferred - loads last) #}
-    <script>
-    (function() {
-        var script = document.createElement('script');
-        script.defer = true;
-        script.src = 'https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js';
-
-        script.onerror = function() {
-            console.warn('Alpine.js CDN failed, loading local copy...');
-            var fallbackScript = document.createElement('script');
-            fallbackScript.defer = true;
-            fallbackScript.src = '{{ url_for("static", path="shared/js/lib/alpine.min.js") }}';
-            document.head.appendChild(fallbackScript);
-        };
-
-        document.head.appendChild(script);
-    })();
-    </script>
-
-    {# 8. Page-specific JavaScript #}
+    {# 7. Page-specific JavaScript (MUST load before Alpine.js) #}
     {% block extra_scripts %}{% endblock %}
 
+    {# 8. LAST: Alpine.js (must be last defer script — auto-initializes on load) #}
+    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js"
+            onerror="var s=document.createElement('script');s.defer=true;s.src='{{ url_for('static', path='shared/js/lib/alpine.min.js') }}';document.head.appendChild(s);"></script>
+
     {# Toast notification container #}
     <div id="toast-container" class="fixed bottom-4 right-4 z-50"></div>