Les concepts
Le vocabulaire de la plateforme, core, feature, module, registre, bloc et extension, et les trois façons d'ajouter une fonctionnalité.
Le reste de cette documentation emploie une dizaine de mots avec un sens précis. Les poser une fois évite de les deviner cinquante fois.
Qui possède quoi
Deux dépôts cohabitent dans la tête du lecteur, et la documentation les distingue par leurs chemins.
| Chemin | Ce que c'est |
|---|---|
src/… | Le code de @lrvo/core, livré dans node_modules. Vous ne le modifiez pas. |
app/…, components/… | Votre projet, généré par npx @lrvo/start. C'est là que vous écrivez. |
La règle qui découle de cette séparation : le core n'est jamais modifié pour ajouter une fonctionnalité applicative. Une mise à jour du paquet doit pouvoir arriver sans conflit.
Les quatre mots du core
Un core est une brique d'infrastructure : la base de données, l'API, le courriel, le stockage, les paiements, le PDF, les tâches planifiées, le chiffrement. Chacun ne connaît que son domaine et ignore les autres. C'est ce qui permet de changer de fournisseur de courriel sans toucher au stockage.
Une feature est une fonctionnalité de plateforme construite sur les cores : l'authentification, l'administration. Une feature utilise plusieurs cores, l'inverse n'arrive jamais.
Un module est un paquet npm @lrvo/module-* qui ajoute une fonctionnalité complète, avec ses tables, ses permissions, ses écrans d'admin et ses routes. Il n'est jamais déclaré à la main : il est découvert au démarrage par scan des dépendances, puis activé par une variable d'environnement.
Un registre est la mécanique qui relie les trois. Le core expose des fonctions d'enregistrement, les modules et votre projet les appellent au démarrage, le core lit le résultat au moment du rendu. C'est ce qui permet d'ajouter une entrée de menu ou une page d'admin sans que le core sache qu'elle existe.
Le vocabulaire du contenu
Ces mots n'apparaissent que si le projet sert des pages publiques.
| Terme | Sens |
|---|---|
| Bloc | Une unité de contenu éditable dans l'éditeur, un titre, un paragraphe, une image, une galerie. Le projet peut en définir de nouveaux. |
| Template | Le composant qui enveloppe le contenu rendu côté public, en-tête et pied de page compris. Fourni par le projet, pas par le module. |
| Résolveur de contenu public | La fonction qui décide si un module répond à une URL donnée à la racine du site. Plusieurs modules peuvent en enregistrer, un ordre de priorité tranche. |
| Manifeste | Le fichier que déclare un module pour se présenter, avec son nom, ses permissions et ses variables d'environnement requises. À ne pas confondre avec les manifestes générés dans app/.lrvo/, qui sont du code produit par l'outillage. |
| Widget | Une carte du tableau de bord de l'admin. Elle se déclare en deux moitiés, une qui charge les données sur le serveur, une qui les affiche dans le navigateur. |
Les trois façons d'ajouter une fonctionnalité
C'est la décision la plus fréquente du projet, et elle se prend par ordre d'engagement croissant.
| Voie | Quand | Où ça vit |
|---|---|---|
| Extension in-projet | La fonctionnalité ne sert qu'à ce projet. | Un fichier app/lrvo.extensions.js qui appelle les fonctions d'enregistrement de l'admin. Voir Étendre l'admin. |
| Module | La fonctionnalité servira dans un deuxième projet. | Un paquet npm publié, avec son cycle de version propre. Voir Créer un module. |
| Modification du core | Le besoin est structurel et concerne tous les projets. | Le dépôt @lrvo/core, donc une publication de version. |
La règle courte : si une fonctionnalité peut vivre en module, elle vit en module. Et tant qu'elle ne sert qu'ici, elle reste une extension in-projet.
L'API d'enregistrement est la même dans les deux premiers cas. Passer d'une extension à un module déplace du code, il ne le réécrit pas.
Étape suivante
Comment ça fonctionne montre ces registres en action, du démarrage du serveur au rendu d'une page.