Étendre l’admin sans toucher au core

La règle de Fraza est simple : le core n’est jamais modifié pour ajouter une fonctionnalité applicative. Une mise à jour du paquet doit pouvoir arriver sans conflit. Ce qui rend la règle tenable, ce sont les registres.

Les registres

Le core expose des fonctions d’enregistrement. Votre projet et les modules les appellent au démarrage, et 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.

Un fichier d’extensions

Regroupez les enregistrements dans un point d’entrée unique, importé une fois depuis le layout racine :

// app/fraza.extensions.js
import { registerNavSection, registerNavItem, registerPage, registerPageMeta } from '@fraza/core/features/admin';

registerNavSection({ id: 'commerce', title: 'Commerce', icon: 'PackageIcon', order: 30, group: 'tools' }, { source: 'project' });
registerNavItem({ id: 'orders', label: 'Commandes', icon: 'PackageIcon', href: '/admin/orders', sectionId: 'commerce', permission: 'orders.view' }, { source: 'project' });

Une page en deux moitiés

La fiche, côté serveur, dit que la page existe, qui peut l’ouvrir et son titre. Le chargeur, côté client, dit où trouver son code. Une page sans fiche répond 404, comme une page dont l’utilisateur n’a pas la permission.

registerPageMeta({ slug: 'orders', title: 'Commandes', permission: 'orders.view' }, { source: 'project' });
registerPage({ slug: 'orders', load: () => import('./OrdersPage.js') }, { source: 'project' });

Le code de la page n’est téléchargé que la première fois qu’elle s’ouvre : l’import() reste dans la fonction load.

Une clé, une source

Chaque appel nomme sa source. Un identifiant déjà pris par le core ou par un module fait échouer le démarrage, avec les deux sources nommées : rien ne remplace en silence la page des utilisateurs. Pour remplacer exprès une entrée d’un module, on le dit avec override: true.

Extension, module ou core ?

1. Extension dans le projet : la fonctionnalité ne sert qu’à ce projet.
2. Module : elle servira dans un deuxième projet. Un paquet npm, avec son propre cycle de version.
3. Modification du core : le besoin est structurel et concerne tous les projets.

Si une fonctionnalité peut vivre en module, elle vit en module. Tant qu’elle ne sert qu’ici, elle reste une extension du projet.

L’API d’enregistrement est la même dans les deux premiers cas : passer d’une extension à un module déplace du code, sans le réécrire. Voir Étendre l’admin et Créer un module.