Aller au contenu
Webcosa Développeurs
RessourcesOuvrir le CMS

#Installation

Il n’y a rien à installer. Le CLI est un seul fichier, scripts/theme.mjs, sans aucune dépendance : il n’importe que des modules node:. Pas de npm install, pas de paquet global, pas de version à tenir à jour séparément du dépôt.

node scripts/theme.mjs aidetheme.mjs — le CLI des thèmes Webcosa node scripts/theme.mjs <commande> [options]

Si cette commande affiche l’aide, tu es prêt. Il reste à enregistrer une clé.

#Prérequis

Node.js≥ 20.13requis

C’est le seul prérequis. Node 22 LTS ou 24 est le choix recommandé : c’est ce sur quoi le CLI est développé et vérifié.

Un éditeur de texteau choix

Aucune extension n’est nécessaire. La coloration Liquid de n’importe quel éditeur convient — le format est celui de Shopify, donc les greffons existants fonctionnent.

Vérifie ce que tu as :

node --versionv24.12.0
Note

D’où vient ce plancher de 20.13. Le dépôt ne fixe aucune version : il n’y a ni champ engines dans package.json, ni .nvmrc. Le plancher est donc celui des API que le script utilise réellement, et deux le fixent :

  • parseArgs de node:util, qui analyse la ligne de commande — stable depuis Node 20 ;
  • fs.watch en mode recursive, dont vit la commande suivre — disponible de longue date sur macOS et Windows, mais sur Linux seulement depuis 20.13.0. En dessous, suivre ne voit passer aucune sauvegarde sur une machine Linux, sans lever la moindre erreur. C’est exactement le genre de panne qu’on met une heure à comprendre.

Sur Node 18, fetch existe mais reste marqué expérimental et écrit un avertissement à chaque appel. Le CLI fonctionne, la sortie devient illisible.

#Où vit le script

Arborescence du dépôt
lyvora-cms/
├── scripts/
│   └── theme.mjs        ← le CLI
├── themes/              ← les thèmes D'ORIGINE, pas un dossier de travail
│   ├── origo/
│   ├── forge/
│   ├── vela/
│   └── piazza/
└── src/

Toutes les commandes s’écrivent depuis la racine du dépôt :

node scripts/theme.mjs lister
Danger

Le dossier themes/ à la racine du dépôt n’est pas un dossier de travail. Il contient les thèmes d’origine, compilés dans src/lib/liquid/catalogue.ts par scripts/compiler-themes.mjs, et proposés à l’installation à tous les sites. Un thème récupéré là finirait au catalogue sans que personne l’ait décidé.

Le CLI le détecte et t’avertit — mais il n’empêche rien :

bash
! /Users/marc/lyvora-cms/themes/atelier est sous le `themes/` du dépôt — celui
  des thèmes d'ORIGINE, compilé dans le catalogue. Préfère `--dossier=` ailleurs.

Travaille ailleurs, avec --dossier=. Faire entrer un thème au catalogue est un geste délibéré, décrit dans Ajouter un thème au catalogue.

#L’utiliser hors du dépôt

Le script est autonome : il ne lit aucun fichier du dépôt, ne résout aucun alias @/, et n’a besoin de rien d’autre que Node. On peut donc le copier à côté de ses thèmes, ou dans un dépôt de thèmes séparé.

bash
mkdir -p ~/themes/outils
cp lyvora-cms/scripts/theme.mjs ~/themes/outils/
node ~/themes/outils/theme.mjs aide
Attention

Une copie ne se met pas à jour toute seule. Le CLI recopie une partie du format des thèmes — les six dossiers, les extensions admises, TAILLE_MAX, FICHIERS_MAX — parce qu’il tourne hors de Next et ne peut pas lire un module TypeScript. La divergence est sans danger : le serveur revalide tout ce qu’il reçoit, donc au pire une copie vieillie enverra un fichier que le serveur refusera avec son propre message. Mais elle ne t’évitera plus l’aller-retour réseau, ce qui est justement sa raison d’être.

#Un dossier de thème, de zéro

Le CLI n’a pas de commande d’initialisation, et c’est volontaire : les trois fichiers indispensables sont si courts qu’une commande pour les écrire coûterait plus à maintenir qu’à taper. Il y a deux vraies façons de commencer.

La plus rapide. Installe un thème d’origine depuis le CMS (Apparence → Thèmes), puis récupère-le :

bash
node scripts/theme.mjs recuperer --theme=Origo --dossier=~/themes/mon-theme

Tu obtiens un thème complet et fonctionnel, avec son .webcosa.json déjà posé.

#Vérifier que tout répond

  1. L’aide s’affiche

    node scripts/theme.mjs aide

    Si tu obtiens command not found: node, c’est Node qui manque, pas le CLI.

  2. La clé est enregistrée

    node scripts/theme.mjs connexion

    La commande vérifie la clé avant de l’écrire : si elle affiche le nom de ton site, l’authentification fonctionne de bout en bout.

  3. Le site répond

    node scripts/theme.mjs lister id nom version rôle modifié 11111111 Origo 1.0.0 publié il y a 3 min 22222222 Chantier 2.1.0 brouillon il y a 4 j

    Une liste vide n’est pas une panne : c’est un site sans thème. Installe-en un depuis le CMS, ou pousse un dossier avec pousser --nouveau.

Astuce

--verbeux détaille chaque appel HTTP — méthode, adresse, site visé, présence de la clé. C’est la première chose à ajouter quand une commande ne fait pas ce qu’on croyait :

bash
node scripts/theme.mjs lister --verbeux

Si une commande échoue, la page des erreurs reprend chaque message avec sa cause et le geste à faire.