Vanilla Static Site auf Cloudflare Pages

Was macht Vanilla Static Site auf Cloudflare Pages?

Kein Build-Schritt. Dateien bearbeiten → Push zu main → Cloudflare Pages deployed automatisch. Schnell, günstig, und du kämpfst nie mit einer Toolchain.

Warum Vanilla (Entscheidungsgrundlage)

• Kein Build/CI-Aufwand; eine 2-zeilige Korrektur ist ein 30-Sekunden-Deploy.
• Kein Framework-Lock-in oder Umschreib-Steuer. „Hinzufügen, nicht umschreiben“ ist die Regel.
• Die gesamte Site ist durchsuchbar, debuggbar und offensichtlich.
• Akzeptierter Kompromiss: mehr manueller DOM-Code. Bei kleiner/mittlerer Größe lohnenswert.

Repo + Deploy

• Ein GitHub-Repo → Cloudflare Pages-Projekt, Auto-Deploy bei Push zu main.
• Pages serviert das Repo-Root. Schöne URLs: /mi-cuenta.html wird unter /mi-cuenta ausgeliefert.
• Functions (Serverless) liegen in /functions (siehe supabase-backend).

Das Deploy-Ritual (bei JEDEM Deploy durchführen)

1. Bearbeite die Dateien.
2. Überprüfe, ob JS kompiliert — verschiebe niemals kaputtes Inline-JS. Extrahiere Inline-<script>-Blöcke und führe vm.compileFunction auf jedem aus; node --check für .js/.cjs. Siehe reference/verify-inline.cjs.
3. Cache-Busting der Assets: node .claude/cache-bust.cjs — stempelt jede assets/**/*.css|js-Referenz im HTML mit ?v=<git-short-hash> und schreibt version.json. Siehe reference/cache-bust.cjs.
4. Erhöhe den Version-Stempel (Single Source of Truth in einer JS-Datei, dezent im Footer angezeigt) und protokolliere ihn. Siehe project-continuity für das Versionierungsschema.
5. Commit (beschreibend, in der Sprache des Projekts) mit dem Co-Author-Trailer, Push zu main.
6. Überprüfe live: curl das deployed Asset und bestätige den neuen Versionsstempel + dass version.json dem ?v= des Assets entspricht (sie müssen übereinstimmen, sonst loopt der Auto-Reloader). Cloudflare-Bot-Schutz blockiert einfache Crawler → verwende einen Browser-User-Agent.

.claude/ ist normalerweise in .gitignore, daher bleiben die Cache-Bust/Verify-Skripte lokal (sie laufen zur Build-Zeit auf deinem Rechner, nicht im Repo).

Cache-Busting + Auto-Reload (beendet das „Sehe ich die alte Version“-Spiel)

Zwei Schichten, beide in reference/:

1. cache-bust.cjs — stempelt ?v=<git hash> bei jedem Deploy auf alle Asset-Referenzen, sodass Browser geändertes CSS/JS neu laden, UND schreibt version.json = {"v":"<hash>"}.
2. Auto-Reloader (reference/auto-reload.js) — ein winziges Skript, das auf jeder Seite eingebunden ist, sein eigenes geladenes ?v= ausliest, /version.json (mit no-store ausgeliefert) pollt und bei Erkennung eines neuen Deploys: lädt beim Tab-Rückkehr (sicherer Moment) neu, zeigt ein Ein-Tipp-„Actualizar“-Banner an, während du hinschaust, und unterbricht nie beim Tippen (window.__noAutoReload Opt-out für Prüfungen/Checkout-Abläufe). Bootstrap-Einschränkung: Beim ersten Mal müssen Benutzer einmal manuell hart refreshen, um den Re-Loader zu laden; danach läuft es automatisch.

Serviere den Marker frisch über _headers:

/version.json
  Cache-Control: no-store, max-age=0

Sicherheits-Header (_headers im Repo-Root)

Immer setzen: Content-Security-Policy (script-src/frame-src/connect-src auf die exakten CDNs + deine Supabase-URL + wss für Realtime beschränken), X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, Permissions-Policy, Strict-Transport-Security. Erkannte Falle: Ein Video-iFrame einbetten erfordert die Player-Domain in frame-src, sonst blockiert der Browser sie stillschweigend.

Wiederverwendbare CSS-Konventionen

• Token-basiertes Theming mit CSS-Variablen; ein data-theme="dark"-Remapping + ein gemeinsam genutzter localStorage-Schlüssel, damit das Theme über Seiten/Tabs hinweg synchronisiert.
• Dark Mode: Kontrast zu bestehen ist nicht genug — du brauchst auch eine sichtbare Ebenenhierarchie (bg < surface < card) mit hellen Stufen + Schatten, sonst wirkt es flach.
• Niemals white/Farben hartcodieren; Tokens verwenden, damit das Theme reagiert.
• Globale .btn/.btn-primary nicht überschreiben; im Scope überschreiben.

Dateien in diesem Skill

• reference/cache-bust.cjs — der Asset-Stempler + version.json-Schreiber.
• reference/auto-reload.js — der Deploy-Auto-Reloader (in eine global geladene JS-Datei einfügen).
• reference/verify-inline.cjs — Kompilierungsprüfung von Inline-<script>-Blöcken vor dem Deploy.
• reference/headers-example — ein Starter-_headers.