Aller au contenu
Webcosa Développeurs
RessourcesOuvrir le CMS

#La boucle locale

Éditer dans son éditeur, sauvegarder, recharger l’onglet, voir. C’est la boucle qu’on veut, et le CLI la donne avec une seule commande. Ce guide dit comment la mettre en place, ce que la commande fait exactement à chaque Cmd+S, et pourquoi il y a un site sur lequel il ne faut jamais la lancer.

#Le fait qui gouverne tout le reste

Il n’existe pas d’aperçu d’un thème brouillon. Le rendu public cherche le thème dont le rôle est publie, et lui seul. « Voir le site », dans l’éditeur de code du CMS comme dans le menu d’un brouillon, ouvre l’adresse publique — donc le thème en ligne, pas celui que tu édites.

Et il n’y a pas non plus de rendu local : le CLI ne sait pas rendre du Liquid, et n’apprendra pas. La raison est développée dans Ce que le CLI ne fait pas, mais elle tient en deux phrases. Un thème ne rend pas du Liquid dans le vide : il rend le site de quelqu’un, avec ses pages, son menu, ses articles, ses réglages — des données qui vivent en base et qui changent pendant qu’on édite. Un moteur local devrait soit les recopier (et afficher un site d’hier), soit les inventer (et afficher un site qui n’existe pas).

Conséquence directe : le thème que tu suis doit être le thème publié du site que tu regardes. Toute la question est de choisir quel site.

#Choisir sa cible avant de commencer

Un site en constructiondéfaut : le bon choix

Personne ne le regarde encore. Publie le thème, suis-le avec --oui-je-sais, et la boucle est immédiate. C’est la situation du guide Créer son premier thème.

Un site de préproduction

Un second site dans le même compte, avec un contenu proche du vrai. C’est la réponse propre quand le site final est en ligne : on y publie, on y suit, on transporte ensuite le thème vers le site réel par export/import ou par un second pousser avec --site=.

Le site en ligne d’un clientdéfaut : à éviter

Suivre son thème publié, c’est modifier en direct ce que voient ses clients à chaque sauvegarde — y compris pendant les vingt secondes où une balise n’est pas refermée. Le CLI refuse, et il a raison. Travaille sur une copie, et publie quand c’est fini : voir Publier.

#Mettre la boucle en place

  1. Se placer dans le dossier du thème

    cd ~/webcosa/forge

    Le CLI cherche .webcosa.json dans le dossier courant puis dans ses parents, comme git avec .git. Il y trouve le site et le thème visés, donc aucune option n’est nécessaire. Si tu n’as pas encore ce dossier :

    node scripts/theme.mjs recuperer --theme=Forge --dossier=~/webcosa/forge

  2. Lancer le suivi

    node scripts/theme.mjs suivreForge · PUBLIÉ /Users/toi/webcosa/forge — 23 fichiers suivis Aperçu : https://cms.webcosa.com/s/mon-client Ctrl+C pour arrêter.

    L’en-tête dit trois choses qu’il faut lire avant de taper quoi que ce soit : le nom du thème, son rôle — PUBLIÉ en vert, brouillon en gris — et le nombre de fichiers effectivement surveillés. Si ce nombre est plus petit que ce que tu attends, un fichier est hors format et a été écarté.

    L’adresse d’aperçu n’apparaît que si le site est désigné par son slug. Avec un uuid, le CLI ne peut pas la construire et te renvoie au CMS.

  3. Sauvegarder un fichier

    Ouvre assets/theme.css, change une valeur, enregistre. Dans le terminal :

    Sortie de « suivre »
      14:32:07  ↑ assets/theme.css

    Recharge l’onglet du site. C’est toute la boucle.

#Ce que « suivre » fait à chaque sauvegarde

Dans l’ordre, et c’est utile à connaître parce que chaque étape explique un comportement qui surprend.

1. Il filtrechemin

Le surveillant écoute le dossier entier, mais tout chemin refusé par le format est ignoré sans un mot : .git/, node_modules/, .DS_Store, les fichiers cachés, et tout ce qui n’a pas exactement deux segments dossier/fichier. Il n’y a pas de liste d’exclusion à tenir à jour — c’est le format qui exclut, par construction.

2. Il attend120 ms

Un éditeur qui enregistre émet deux à quatre événements pour une seule sauvegarde. Sans anti-rebond, le même contenu partirait quatre fois et ferait quatre écritures en base. Le compteur est par fichier : sauvegarder dix fichiers d’un coup les pousse tous les dix.

3. Il compareSHA-256

L’empreinte du contenu est comparée à la dernière connue. Un enregistrement qui ne change rien — Cmd+S réflexe, reformatage sans effet — ne produit aucun appel réseau et aucune ligne dans le terminal. Un silence après une sauvegarde n’est donc pas une panne : c’est qu’il n’y avait rien à envoyer.

4. Il envoiePUT

Un fichier à la fois, séquentiellement. Le serveur valide la syntaxe Liquid avant d’écrire ; un fichier refusé n’est pas enregistré.

#Ce qu’il ne fait pas

Attention

suivre n’efface jamais rien à distance. Un fichier supprimé en local est signalé, pas supprimé en base :

  ? disparu   sections/vieille-section.liquid (`pousser --supprimer` pour l'effacer)

La raison est prosaïque : un éditeur qui enregistre remplace souvent le fichier par un temporaire, ce qui le fait disparaître une fraction de seconde. Si ce clignotement supprimait en base, une sauvegarde ordinaire détruirait du travail.

suivre ne surveille pas non plus les créations de dossier au-delà de ce que le format connaît, et ne relit pas .webcosa.json en cours de route : changer de thème ou de site demande de relancer la commande.

#Quand la syntaxe est fausse

C’est le cas normal du travail, pas une exception. Une accolade pas encore refermée pendant la frappe est un état transitoire, et le suivi ne s’arrête pas :

Sortie de « suivre »
  14:35:12  ✗ sections/horaires.liquid — tag "for" not closed, line:14, col:1 [syntaxe]
  14:35:41  ↑ sections/horaires.liquid

Trois choses à savoir :

  • Le fichier fautif n’est pas enregistré. La version en base reste la dernière qui compilait — le site en ligne ne casse pas parce que tu tapes.
  • Le suivi continue. Sortir sur chaque erreur obligerait à relancer la commande toutes les deux minutes.
  • La ligne et la colonne viennent de l’analyseur, pas de nous. Elles portent sur le fichier tel qu’il a été envoyé.

Une erreur qui n’est pas de syntaxe s’affiche pareil mais vient d’ailleurs : un 403 de portée insuffisante, un 402 de site inactif, un 429 de limitation de débit. La liste complète est dans Erreurs.

Note

Une erreur de rendu — boucle trop longue, section absente, imbrication trop profonde — n’apparaît jamais ici. La syntaxe est correcte, l’écriture réussit, et le problème ne se voit qu’au rendu, sous forme de commentaire HTML dans la page. Voir Le bac à sable.

#Pourquoi on ne suit pas un thème publié

Lancée sur le thème en ligne, la commande s’arrête et pose une question :

Sortie de « suivre »
! « Forge » est le thème PUBLIÉ : chaque sauvegarde irait en ligne.

En dupliquer une copie brouillon et suivre la copie ? [o/N]

Ce n’est pas une précaution de principe. Suivre un thème publié, c’est publier chaque état intermédiaire de ton travail : la balise pas encore refermée, la couleur essayée puis regrettée, la section à moitié écrite. Sur un site que des clients regardent, ces vingt secondes sont vues. Shopify pose le même garde-fou, et propose la même issue.

  1. Répondre « o » — la voie normale

    Le CLI duplique le thème, obtient une copie en brouillon, met à jour .webcosa.json pour qu’il vise la copie, et suit celle-ci.

    Sortie de « suivre »
    ✓ Copie créée : Forge (copie) 22222222-2222-4222-8222-222222222222

    La mise à jour du fichier de projet n’est pas cosmétique : sans elle, le pousser suivant repartirait sur le thème publié — exactement ce qu’on vient d’éviter.

    Mais rappelle-toi le premier paragraphe de cette page : la copie est un brouillon, donc invisible. Tu peux travailler, tu ne verras rien tant que tu ne l’auras pas publiée. C’est le prix de la sécurité, et c’est pourquoi la préproduction reste la meilleure réponse.

  2. Répondre « n »

    Sortie de « suivre »
    ✗ Suivi annulé.
  Passe `--oui-je-sais` si tu veux vraiment éditer le thème en ligne.

  3. Forcer, en connaissance de cause

    node scripts/theme.mjs suivre --oui-je-sais

    Légitime sur un site que personne ne regarde encore : la boucle est immédiate, et il n’y a rien à casser. Illégitime sur un site en ligne, et le nom de l’option est fait pour qu’on ne puisse pas dire qu’on ne savait pas.

#Dupliquer avant de travailler, sans passer par « suivre »

Trois chemins pour la même chose, selon où tu es.

Site web → le menu à trois points du thème → Dupliquer. La copie arrive en brouillon, nommée « … (copie) ». Renomme-la dans le même menu : ce nom n’apparaît que dans ton espace, jamais sur le site.

#Travailler à plusieurs sur le même thème

Le distant est le seul exemplaire : il n’y a ni corbeille, ni historique, ni version précédente. Deux règles suffisent à ne rien perdre.

Danger

Ne lance jamais pousser --supprimer --force sur un thème que quelqu’un d’autre édite. --supprimer retire du distant les fichiers absents en local ; --force saute la confirmation. La combinaison efface définitivement la section qu’un collègue vient d’ajouter depuis l’éditeur du CMS, sans qu’aucune question n’ait été posée. Elle existe pour l’intégration continue, qui n’a pas de terminal pour répondre — pas pour une machine de développement.

Sans --supprimer, pousser signale les orphelins et n’y touche pas :

! 1 fichier(s) existent à distance mais pas en local — non touchés :
    sections/temoignages.liquid
    Ajoute `--supprimer` pour les retirer du thème distant.

C’est le bon moment pour faire un recuperer : il écrira les fichiers manquants sur ton disque, et listera ceux qu’il s’apprête à écraser en demandant confirmation.

#En résumé

La boucle courtedéfaut : site de préproduction

suivre --oui-je-sais sur le thème publié d’un site que personne ne regarde. Édition, sauvegarde, rechargement : trois secondes.

La boucle sûredéfaut : site en ligne

Dupliquer, suivre la copie, publier à la fin. On ne voit rien pendant, on contrôle tout à l’arrivée.

PublierBrouillon, publication, retour arrière : ce que voit le client à chaque étape.CommandesRéférence complète : `lister`, `recuperer`, `pousser`, `suivre`, `publier` et leurs options.ErreursChaque message d'erreur du CLI, ce qu'il signifie, et quoi faire.