Site statique Vanilla sur Cloudflare Pages

Que fait Site statique Vanilla sur Cloudflare Pages ?

Aucune étape de build. Modifiez les fichiers → poussez sur main → Cloudflare Pages se déploie automatiquement. Rapide, économique, et vous ne luttez jamais contre une chaîne d'outils.

Pourquoi vanilla (décision justifiée)

• Aucun churn de build/CI ; une correction de copie de 2 lignes est un déploiement de 30 secondes.
• Pas de verrouillage framework ni de taxe de réécriture. « Ajoutez, ne réécrivez pas » est la règle.
• L'ensemble du site est « greppable », débogable et évident.
• Compromis accepté : plus de code DOM manuel. Cela en vaut la peine à petite/moyenne échelle.

Dépôt + déploiement

• Un dépôt GitHub → projet Cloudflare Pages, déploiement automatique sur push vers main.
• Pages sert la racine du dépôt. URLs propres : /mon-compte.html est servi à /mon-compte.
• Les fonctions (serverless) vivent dans /functions (voir supabase-backend).

Le rituel de déploiement (faites-le à CHAQUE déploiement)

1. Modifiez les fichiers.
2. Vérifiez que le JS compile — ne poussez jamais du JS inline cassé. Extrayez les blocs <script> inline et exécutez vm.compileFunction sur chacun ; node --check pour les .js/.cjs. Voir reference/verify-inline.cjs.
3. Cache-bustez les actifs : node .claude/cache-bust.cjs — estampe chaque référence assets/**/*.css|js dans le HTML avec ?v=<hash-git-court> et écrit version.json. Voir reference/cache-bust.cjs.
4. Incrémentez le numéro de version (source unique de vérité dans un fichier JS, affiché subtilement dans le pied de page) et enregistrez-le. Voir project-continuity pour le schéma de versionnage.
5. Commitez (descriptif, dans la langue du projet) avec le suffixe co-auteur, poussez sur main.
6. Vérifiez en direct : curl l'actif déployé et confirmez le nouveau numéro de version + que version.json est égal à ?v= de l'actif (ils doivent correspondre ou le rechargement automatique boucle). La protection anti-bot de Cloudflare bloque les crawlers simples → utilisez un User-Agent de navigateur.

.claude/ est généralement dans .gitignore, donc les scripts de cache-bust/vérification restent locaux (ils s'exécutent au moment de la construction sur votre machine, pas dans le dépôt).

Cache-busting + rechargement automatique (tue le jeu du téléphone « on ne voit pas »)

Deux couches, toutes deux dans reference/ :

1. cache-bust.cjs — ré-estampe ?v=<hash git> sur toutes les références d'actifs à chaque déploiement afin que les navigateurs re-téléchargent le CSS/JS modifié, ET écrit version.json = {"v":"<hash>"}.
2. Rechargeur automatique (reference/auto-reload.js) — un petit script inclus sur chaque page qui lit son propre ?v= chargé, interroge /version.json (servi avec no-store), et lorsqu'un nouveau déploiement est détecté : recharge au retour sur l'onglet (moment sûr), affiche une bannière « Actualiser » en un clic pendant que vous regardez, et n'interrompt jamais en pleine saisie (window.__noAutoReload pour les flux d'examen/checkout). Piège Bootstrap : la première fois, les utilisateurs font un rafraîchissement forcé une fois pour charger le rechargeur ; ensuite c'est automatique.

Servez le marqueur frais via _headers :

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

En-têtes de sécurité (_headers à la racine du dépôt)

Toujours définir : Content-Security-Policy (verrouillez script-src/frame-src/connect-src aux CDN exacts + votre URL Supabase + wss pour le temps réel), X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, Permissions-Policy, Strict-Transport-Security. Piège vécu : intégrer une iframe vidéo nécessite le domaine du lecteur dans frame-src sinon le navigateur la bloque silencieusement.

Conventions CSS réutilisables

• Thématisation basée sur des tokens avec des variables CSS ; une remappe data-theme="dark" + une clé localStorage partagée pour que le thème se synchronise entre les pages/onglets.
• Mode sombre : passer les contrastes ne suffit pas — il faut aussi une hiérarchie de couches visible (bg < surface < carte) avec des paliers de lumière + ombre, sinon tout semble plat.
• Ne codez jamais en dur white/couleurs ; utilisez des tokens pour que le thème réponde.
• Ne cassez pas les .btn/.btn-primary globaux ; remplacez-les dans la portée.

Fichiers dans cette compétence

• reference/cache-bust.cjs — l'estampeur d'actifs + l'écrivain de version.json.
• reference/auto-reload.js — le rechargeur automatique de déploiement (à inclure dans un fichier JS chargé globalement).
• reference/verify-inline.cjs — vérifie la compilation des blocs <script> inline avant le déploiement.
• reference/headers-example — un fichier _headers de démarrage.