Création d’un module frontend

OpenMRS publie @openmrs/create-o3-app, un générateur pour créer des modules frontend O3. Les auteurs de modules devraient l’exécuter avec l’initialiseur create de npm, sous la forme npm create @openmrs/o3-app@latest. Le code source du générateur se trouve dans openmrs/create-o3-app, et le module frontend Template reste utile comme référence pour la structure générée.

Incluez toujours le scope @openmrs/. Le package npm non scopé create-o3-app est un projet tiers sans rapport, donc les commandes comme npx create-o3-app ... récupèrent le mauvais outil. Utilisez npm create @openmrs/o3-app@latest ... ou npx @openmrs/create-o3-app@latest ....

Prérequis

Node.js 20 ou plus récent.
Corepack activé, afin que la version de Yarn épinglée par le projet généré fonctionne sans installation séparée de Yarn. Si Corepack n’est pas encore activé, lancez corepack enable une fois.

Démarrage rapide

Lancez le générateur depuis le répertoire où le nouveau dossier de module doit être créé:


npm create @openmrs/o3-app@latest active-prescriptions

Cette commande crée un module de page autonome avec les valeurs par défaut du CLI. Dans les répertoires où le CLI détecte un monorepo existant, il peut demander s’il faut ajouter le module à ce monorepo. Si npm create n’est pas votre habitude, la commande npx scopée équivalente est:


npx @openmrs/create-o3-app@latest active-prescriptions

Exemple: prescriptions actives

Supposons que vous souhaitiez créer un module frontend qui fournit une interface pour afficher les prescriptions actives. Notre objectif est de recréer l’onglet Active Prescriptions de openmrs-esm-dispensing-app.

Générer le module

Pour une commande répétable et adaptée à la CI, passez les flags explicites après le séparateur -- de npm:


npm create @openmrs/o3-app@latest active-prescriptions -- \
  --standalone \
  --package-name "@openmrs/esm-active-prescriptions-app" \
  --route "/active-prescriptions" \
  --route-component "ActivePrescriptions" \
  --no-git \
  --quiet

Le séparateur -- est obligatoire pour transmettre des flags via npm create. Rspack est l’outil de build par défaut; ajoutez --webpack uniquement si vous avez besoin d’un scaffold Webpack.

ℹ️

Pourquoi le préfixe esm? Les modules frontend utilisent par convention des noms de package qui commencent par esm. Consultez l’aperçu des modules frontend.

Lancer le module localement

Le répertoire généré est basé sur le nom du package. Pour la commande ci-dessus, entrez dans le projet généré et démarrez le shell O3 local:


cd openmrs-esm-active-prescriptions-app
corepack yarn install
corepack yarn start

Pour les modules autonomes, le CLI installe automatiquement les dépendances sauf si l’installation est ignorée, interrompue ou si vous avez utilisé --dry-run, mais lancer corepack yarn install reste sûr lorsque vous récupérez ou reprenez un projet généré. L’application devrait être disponible sur http://localhost:8080/openmrs/spa/active-prescriptions. Utilisez l’identifiant admin et le mot de passe Admin123 pour le backend de développement par défaut.

Utilisez corepack yarn start --port <port> pour choisir un autre port. Utilisez corepack yarn start --backend <url> pour pointer le shell de développement vers un autre backend OpenMRS, par exemple corepack yarn start --backend http://localhost.

Personnaliser les fichiers générés

Vérifiez d’abord les fichiers que la plupart des modules modifient:

src/constants.ts exporte le moduleName du package.
src/routes.json enregistre les pages et extensions auprès de l’app shell.
src/config-schema.ts définit la configuration runtime.
src/active-prescriptions.component.tsx est le composant de page généré.
translations/en.json contient les chaînes de traduction de départ.

Le module généré inclut aussi src/index.ts, src/root.component.tsx, la configuration de build choisie (rspack.config.js par défaut), un test de départ src/root.component.test.tsx, Vitest avec jsdom, ESLint, Prettier, Husky et l’extraction des traductions. src/routes.json mappe la route /active-prescriptions au lifecycle exporté root, et root.component.tsx rend le composant de route. Si vous générez un module avec des extensions, le même modèle crée des fichiers de composants d’extension et exporte leurs lifecycles depuis src/index.ts.

Prévisualiser sans écrire de fichiers

Utilisez --dry-run pour voir ce qui serait créé sans écrire de fichiers, installer les dépendances ni initialiser Git:


npm create @openmrs/o3-app@latest active-prescriptions -- --dry-run

Flags courants

Flag	Utilisation
`--standalone`	Crée un module autonome, qui est la valeur par défaut hors d’un monorepo détecté.
`--monorepo`	Ajoute un module au monorepo courant et utilise le chemin de package par défaut.
`--new-monorepo`	Crée un nouveau monorepo racine avec ce module comme premier package.
`--package-name <name>`	Définit le nom du package npm, par exemple `@openmrs/esm-active-prescriptions-app`.
`--route <route>`	Définit le chemin de route d’un module de page. À utiliser avec `--route-component`.
`--route-component <name>`	Définit le nom du composant React pour la route de page. À utiliser avec `--route`.
`--webpack`	Utilise Webpack au lieu de la configuration Rspack par défaut.
`--no-git`	Ignore l’initialisation Git.
`--no-ci`	Réservé au support des workflows CI générés. Le template actuel accepte le flag mais ne produit pas encore de fichiers de workflow.
`--dry-run`	Prévisualise les fichiers générés sans les écrire.
`--quiet`	Réduit la sortie et utilise les valeurs par défaut lorsque possible.
`--verbose`	Affiche une sortie plus détaillée.

--rspack existe seulement comme flag de compatibilité déprécié, car Rspack est déjà la valeur par défaut.

Monorepos

Monorepo existant

Depuis la racine du monorepo, lancez:


npm create @openmrs/o3-app@latest referrals-queue -- --monorepo

Le CLI utilise le chemin de package par défaut packages/apps/esm-referrals-queue et met à jour la configuration de workspace lorsqu’il détecte un fichier de workspace pris en charge.

Nouveau monorepo

Pour créer un nouveau monorepo racine avec le module généré comme premier package, lancez:


npm create @openmrs/o3-app@latest referrals-workspace -- --new-monorepo

Le CLI crée le projet racine et place le module sous packages/apps/esm-referrals-workspace.

Publier et ajouter à une distribution

Une fois le module frontend prêt, publiez le package sur npm. Le package devrait ensuite être visible sur npmjs.com, par exemple @openmrs/esm-login-app.

Pour inclure le module dans une distribution, ajoutez-le à l’objet frontendModules du fichier spa-assemble-config.json de la distribution:

spa-assemble-config.json


{
  "frontendModules": {
    "@openmrs/esm-active-prescriptions-app": "1.0.0"
  }
}

Utilisez une version testée pour les distributions de release. Pour plus d’informations, consultez le guide Créer une distribution et le guide Vue d’ensemble de la configuration.