Développer des modules frontend

Après avoir configuré un module frontend localement, vous voudrez commencer à le modifier. Ce guide présente les étapes du développement local d’un module frontend: installer les dépendances, exécuter des modules localement, écrire des tests, pousser vos changements vers GitHub, maintenir les dépendances et résoudre les problèmes courants.

Installer les dépendances

La plupart des dépôts frontend épinglent leur gestionnaire de paquets dans package.json et, pour les dépôts Yarn Berry, dans .yarnrc.yml. Utilisez la version de Yarn déclarée par le dépôt, puis allez dans votre copie locale du module frontend sur lequel vous voulez travailler et lancez yarn, qui est un raccourci pour yarn install. Par exemple, pour travailler sur le module frontend Patient Chart :

cd openmrs-esm-patient-chart
yarn

Exécuter des modules frontend localement

Dépôts non monorepos

Certains projets ne sont pas des monorepos. Par exemple, Form Builder  est un projet autonome. Pour exécuter Form Builder localement, entrez dans le dossier du projet et lancez yarn start:

cd openmrs-esm-form-builder
yarn start

Dans les dépôts qui ne sont pas des monorepos, vous ne devriez pas avoir besoin de limiter les commandes à des packages cibles.

Monorepos

La plupart de nos modules frontend font partie de monorepos. Par exemple, le monorepo Patient Chart  contient plusieurs modules frontend liés au patient. Vous voudrez généralement exécuter un module frontend précis dans un monorepo. Pour cela, lancez yarn start --sources et passez le chemin relatif du module cible. Par exemple, pour exécuter uniquement le module Vitals :

yarn start --sources packages/esm-patient-vitals-app

L’argument qui suit --sources est le chemin relatif du module frontend à exécuter.

Si le workspace peut résoudre les packages par nom, vous pouvez aussi utiliser --packages au lieu des chemins de fichiers:

yarn start --packages @openmrs/esm-patient-vitals-app

Il est possible d’exécuter plusieurs modules frontend en même temps. Par exemple, si vous modifiez l’Order Basket , vous voudrez probablement tester ces changements avec les modules Medications et Orders. Pour cela:

yarn start --sources packages/esm-patient-medications-app packages/esm-patient-orders-app

Cette commande démarre un serveur de développement du bundler avec des copies locales des modules Medications et Orders. Les modules React actuels utilisent Rspack, tandis que quelques modules plus anciens peuvent encore utiliser Webpack. Les changements locaux devraient se propager au serveur de développement dans votre navigateur.

Par défaut, le serveur de développement s’exécute sur le port 8080. Pour utiliser un autre port, passez un numéro de port à l’option --port. Par exemple, pour exécuter le module Vitals sur le port 7000:

yarn start --sources 'packages/esm-patient-vitals-app' --port=7000

Cela démarre l’app shell sur http://localhost:7000/openmrs/spa et sert le module sur le port disponible suivant, généralement http://localhost:7001.

Utiliser les surcharges d’import map

O3 détermine où charger le code des modules frontend à partir de l’import map fournie à l’app shell. L’import map est un objet JSON qui associe des spécificateurs de module à des URLs. Vous pouvez trouver l’import map de votre distribution O3 en ouvrant /openmrs/spa/importmap.json dans votre navigateur. L’app shell lit aussi /openmrs/spa/routes.registry.json pour découvrir les métadonnées de routes et d’extensions de chaque module.

Le module frontend Devtools  fournit une interface pour surcharger les entrées de l’import map. Quand vous surchargez l’URL d’un module, Devtools ajoute aussi un override de route map correspondant qui pointe vers le routes.json placé à côté du bundle local. Vous pouvez l’utiliser pendant le développement local pour charger des copies de vos modules frontend depuis votre serveur de développement local. Par exemple, si vous lancez un serveur local avec l’app shell, vous pouvez surcharger plusieurs modules frontend issus de plusieurs projets en même temps. C’est utile quand vous travaillez sur une fonctionnalité qui traverse plusieurs modules.

Exemple: exécuter les modules Implementer tools et Primary navigation contre l’app shell

cd openmrs-esm-core
yarn run:shell

cd openmrs-esm-core
yarn start --sources packages/apps/esm-implementer-tools-app --port=7000

cd openmrs-esm-core
yarn start --sources packages/apps/esm-primary-navigation-app --port=9000

localStorage.setItem('openmrs:devtools', 'true')

Exécuter esm-patient-common-lib localement

esm-patient-common-lib est une bibliothèque de composants et d’utilitaires partagés, utilisée principalement par le patient chart dans O3. Vous pouvez vouloir modifier cette bibliothèque et tester les changements contre un serveur de développement local. Pour cela:

• Ouvrez le fichier package.json du module frontend sur lequel vous voulez travailler. Cherchez la dépendance esm-patient-common-lib dans peerDependencies. Supprimez cette entrée, puis lancez yarn pour installer les dépendances.

• Lancez votre serveur de développement local avec yarn start. Par exemple, pour l’app labs:

  yarn start --sources 'packages/esm-patient-labs-app'

• Essayez de modifier la bibliothèque, par exemple en ajoutant un console.log dans un fichier comme DashboardExtension.tsx. Votre serveur de développement devrait se recharger et vous devriez voir le console.log dans la console du navigateur après avoir ouvert le patient chart.

• Quand vous avez terminé, annulez les changements faits dans package.json, puis relancez yarn pour réinstaller les dépendances.

Exécuter l’app shell localement

L’exécution de modules individuels avec yarn start suffit généralement à lancer un serveur de développement local. L’une des exceptions notables est l’exécution directe de l’app shell. Vous devrez lancer le shell directement si vous voulez:

• Modifier le module frontend styleguide et tester ces changements localement.

• Tester des changements dans les applications suivantes:

  • devtools - utilisée pour configurer les surcharges d’import map et de routes.
  • implementer tools - utilisée pour configurer les extensions et composants d’interface à la volée.
  • login - la page de connexion de l’application de référence.
  • offline tools - le tableau de bord des outils hors ligne.
  • primary navigation - le menu de navigation.

Pour lancer l’app shell, entrez dans le monorepo esm-core et exécutez:

yarn run:shell

Cette commande démarre un serveur de développement à http://localhost:8080/openmrs/spa. Vous pouvez ensuite ouvrir l’app shell à http://localhost:8080/openmrs/spa/shell, puis naviguer vers les applications à tester.

Comme ces applications se trouvent dans le dossier apps du monorepo esm-core, les exécuter dans le contexte de l’app shell rend les tests locaux beaucoup plus simples. À noter toutefois: pour que vos changements se propagent au serveur local, vous devrez peut-être reconstruire votre module frontend. Pour cela:

yarn turbo build

Cette commande exécute le script build dans tous les modules frontend concernés par vos changements. Une fois le build terminé, vos changements devraient apparaître dans le navigateur.

Comment savoir où faire des changements?

Il n’existe pas de corrélation simple entre modules frontend, pages et contenu. La première étape consiste à identifier le module frontend à modifier. Par exemple, pour modifier le patient chart, vous travaillerez dans le module patient-chart. Pour modifier la recherche patient, vous travaillerez dans le module patient-search. Pour modifier la page de connexion, vous travaillerez dans le module login, et ainsi de suite. Quelques méthodes aident à trouver le bon module:

• Inspectez un élément dans le navigateur et regardez son nom de classe. Cherchez ensuite ce nom de classe dans votre IDE. Cela devrait vous amener au morceau de code précis à modifier.
• Cherchez des chaînes spécifiques dans la base de code. Par exemple, si vous voyez le texte Vitals history dans l’interface, cherchez cette chaîne dans votre IDE. Cela devrait pointer vers le module frontend qui rend ce texte, ici le module vitals.
• Utilisez aussi l’éditeur d’interface dans les implementer tools pour voir quelles extensions et quels extension slots sont rendus dans l’interface. Vous pourrez ensuite chercher ces extensions et slots dans votre IDE. C’est un peu plus impliqué, mais c’est un bon moyen de comprendre la structure de l’interface et les modules frontend qu’elle contient.
• Parcourez la liste des dépôts clés et leurs descriptions. Il n’y en a pas énormément et ils sont généralement liés à un domaine, donc vous pourrez souvent réduire le champ simplement en lisant la liste.

Il n’y a pas de règle stricte pour trouver où faire un changement. Essayez plusieurs approches et gardez celle qui fonctionne. Plus vous travaillerez dans la base de code, plus vous la connaîtrez et plus il sera facile de localiser les changements à faire. Si vous avez essayé toutes les approches ci-dessus sans trouver le code recherché, demandez de l’aide dans le canal Slack #openmrs-helpme .

Travailler sur un ticket (flux pratique)

Si vous prenez un ticket et voulez avancer efficacement, ce flux fonctionne généralement bien:

1. Trouvez le bon dépôt ou module avec les techniques ci-dessus.
2. Exécutez le module localement et reproduisez le problème ou vérifiez le besoin.
3. Faites le changement en gardant les conventions de code en tête.
4. Vérifiez localement avec un test UI et les tests pertinents.
5. Mettez à jour les traductions si vous ajoutez ou modifiez des chaînes visibles par l’utilisateur.
6. Ouvrez une PR avec un résumé clair et des captures si l’interface change.

Blocages courants à surveiller:

• Accès backend/authentification: Vous aurez besoin d’un backend OpenMRS fonctionnel, dev3 ou local. Si la connexion échoue, vérifiez que vous utilisez des identifiants valides pour cet environnement.
• Surcharges d’import map et de routes: Si un changement n’apparaît pas, vérifiez les surcharges Devtools et faites un hard refresh pour que l’app shell relise l’import map et le registre de routes.
• URLs attendues: L’app shell s’exécute à /openmrs/spa et votre module local peut être servi depuis un autre port.
• Feature flags: Si vous ne voyez pas une nouvelle interface, vérifiez si elle est derrière un feature flag dans le menu feature flags des Implementer Tools.

Récupération de données et mutations

La plupart des travaux sur un module frontend finissent par toucher des données backend. Préférez les utilitaires du framework O3 et les hooks de ressources déjà présents dans le dépôt:

• Utilisez openmrsFetch avec des hooks SWR plutôt qu’un appel direct à fetch. openmrsFetch résout les URLs relatives à OpenMRS, définit les en-têtes habituels pour JSON et l’API REST OpenMRS, analyse les réponses et gère les erreurs.
• Utilisez les URLs de base du framework, comme restBaseUrl et fhirBaseUrl, plutôt que de coder /ws/rest/v1 ou les chemins FHIR partout dans les composants.
• Gardez l’accès aux données dans des fichiers de ressources ou des hooks personnalisés, puis retournez l’état SWR (data, error, isLoading ou isValidating, et mutate) aux composants.
• Après une mutation réussie, mettez à jour le cache SWR concerné avec mutate pour éviter un rechargement complet de l’interface.

Pour des exemples, consultez la recette Récupérer et publier des données, ainsi que les conventions Récupération des données, États de chargement et Mutations et effets secondaires.

Comment développer contre un environnement restreint?

En général, vous pouvez développer contre un autre environnement avec l’option --backend. Si cet environnement est protégé, par exemple par une restriction IP ou réseau, vous devrez régler cela sur votre machine locale. Si l’environnement est protégé par un mécanisme SSO qui utilise un cookie, vous pouvez utiliser l’option --add-cookie. Par exemple, pour accéder à un serveur de développement de l’ICRC:

yarn start --backend "https://emr-v2.test.icrc.org/" --add-cookie "MRHSession=1234..."

Le cookie doit être obtenu par vous et dépend fortement du backend utilisé. Utilisez npx openmrs start avec les mêmes options lorsque vous avez seulement besoin de lancer l’app shell en dehors d’un dépôt de module frontend.

Dois-je écrire des tests?

Oui, absolument. Les modules React actuels utilisent généralement Vitest  et React Testing Library  pour les tests de composants, même si certains dépôts plus anciens utilisent encore Jest . Consultez le package.json du module pour voir quel runner est configuré. Voir le guide de tests unitaires et d’intégration et le guide de tests de bout en bout pour plus d’informations. Envisagez aussi d’ajouter des tests E2E pour les workflows importants. Lire les tests voisins dans la base de code est souvent le moyen le plus rapide d’aligner vos tests sur les conventions du dépôt.

Pousser vos changements vers GitHub

Une fois votre fonctionnalité ou correction terminée, vous voudrez pousser vos changements vers GitHub et ouvrir une PR. Pour cela, regroupez vos changements dans un commit. Nous avons des recommandations pour les messages de commit dans le guide de contribution.

Créer un commit déclenche généralement des hooks pre-commit. Une partie de leur travail consiste souvent à exécuter yarn run extract-translations. Cette tâche lance turborepo et exécute extract-translations dans chaque package du monorepo. Elle extrait les clés et chaînes de traduction et met à jour le fichier de traductions de la locale par défaut, généralement en.json dans le dossier translations de votre module frontend. Committez les changements de traduction générés avec le code qui les introduit. Après l’exécution des hooks pre-commit, vous voudrez pousser vos changements vers GitHub. Le push déclenchera un hook pre-push qui exécute généralement ces tâches en parallèle avec turborepo:

• typescript - vérifie les types de votre application.
• lint - lance ESLint, généralement avec les warnings traités comme des échecs.
• test - lance les tests, avec Jest ou Vitest selon le dépôt.

Si l’une de ces tâches échoue, le push devrait échouer. Le terminal affichera les messages d’erreur responsables. Corrigez-les puis poussez à nouveau. Une fois le push réussi, vous pouvez ouvrir une pull request dans le dépôt GitHub lié à votre package.

Maintenir les dépendances

Maintenir les dépendances à jour est important pour bénéficier des dernières fonctionnalités, améliorations de performance et correctifs de sécurité. La plupart des dépôts frontend actuels utilisent Yarn 4, mais vérifiez toujours le champ packageManager dans package.json, car certains dépôts plus anciens diffèrent. Yarn fournit un outil interactif pratique pour cela:

yarn upgrade-interactive

Cette commande liste les dépendances pouvant être mises à jour. Vous pouvez naviguer dans la liste avec les flèches du clavier. En général, évitez les mises à jour majeures sauf si vous traitez volontairement des changements incompatibles. Gardez les dépendances d’outillage OpenMRS comme openmrs et @openmrs/esm-framework épinglées sur next dans devDependencies, mais conservez les plages semver prises en charge déjà utilisées dans peerDependencies. Le reste peut généralement être mis à jour vers la dernière version compatible. Après avoir sélectionné les dépendances à mettre à jour, appuyez sur Enter, puis testez l’app, lancez les tests pertinents et vérifiez que le build fonctionne.

Dépannage

J’obtiens beaucoup d’erreurs liées à des dépendances manquantes

Si vous travaillez depuis un fork, votre branche peut ne pas contenir les derniers changements de main. Récupérez le dépôt upstream, puis mettez votre branche à jour depuis upstream/main avec le flux normal du dépôt. Par exemple:

git fetch upstream
git merge upstream/main

J’obtiens une erreur Error: ENOSPC: System limit for number of file watchers reached

Si vous êtes sous Linux, vous pouvez voir cette erreur la première fois que vous lancez un serveur de développement: Error: ENOSPC: System limit for number of file watchers reached. Dans ce cas, augmentez la limite système du nombre de file watchers. Voir cette réponse StackOverflow .

Je vois des erreurs d’API manquantes quand je lance l’app

Si votre serveur de développement affiche des erreurs liées à des APIs ou fonctions manquantes, vous utilisez probablement des versions obsolètes du framework ou de l’outillage core. Cela signifie souvent qu’une nouvelle fonctionnalité a été ajoutée à Core  et que votre serveur local ne l’a pas encore. De nouvelles versions pre-release du CLI openmrs  et de @openmrs/esm-framework  sont publiées à chaque merge de PR dans Core. Pour obtenir les dernières versions:

yarn up openmrs@next @openmrs/esm-framework@next

Cette commande peut modifier les versions indiquées dans votre manifeste (package.json). Si c’est le cas, gardez les dépendances d’outillage OpenMRS comme openmrs et @openmrs/esm-framework épinglées sur next avant de committer. Les plages de peerDependencies doivent rester alignées sur celles déjà utilisées par le dépôt. Vous devrez peut-être relancer yarn après avoir ajusté le manifeste pour que le lockfile reflète les packages publiés les plus récents. Relisez toujours le diff de package.json avant de committer. Si les seuls changements du manifeste sont des résolutions temporaires vers next, certains contributeurs utilisent un alias comme celui-ci:

alias bump-core-tooling="yarn up openmrs@next @openmrs/esm-framework@next && git restore package.json && yarn"

N’utilisez cet alias que si vous n’avez aucune modification intentionnelle de package.json à préserver.

J’obtiens une erreur ERR_OSSL_EVP_UNSUPPORTED quand je lance yarn run build

Si vous exécutez ou construisez le package form-entry, un wrapper Angular autour d’AMPATH Form Engine, avec une combinaison Node/OpenSSL qui refuse les anciens algorithmes de hash, vous pouvez voir l’erreur suivante:

Error: error:0308010C:digital envelope routines::unsupported
    at new Hash (node:internal/crypto/hash:71:19)
    at Object.createHash (node:crypto:133:10)
    at BulkUpdateDecorator.hashFactory (/path/to/openmrs-esm-patient-chart/node_modules/@angular-devkit/build-angular/node_modules/webpack/lib/util/createHash.js:145:18)
    at BulkUpdateDecorator.update (/path/to/openmrs-esm-patient-chart/node_modules/@angular-devkit/build-angular/node_modules/webpack/lib/util/createHash.js:46:50)
    at RawSource.updateHash (/path/to/openmrs-esm-patient-chart/node_modules/webpack-sources/lib/RawSource.js:77:8)
    at NormalModule._initBuildHash (/path/to/openmrs-esm-patient-chart/node_modules/@angular-devkit/build-angular/node_modules/webpack/lib/NormalModule.js:880:17)
    at handleParseResult (/path/to/openmrs-esm-patient-chart/node_modules/@angular-devkit/build-angular/node_modules/webpack/lib/NormalModule.js:946:10)
    at /path/to/openmrs-esm-patient-chart/node_modules/@angular-devkit/build-angular/node_modules/webpack/lib/NormalModule.js:1040:4
    at processResult (/path/to/openmrs-esm-patient-chart/node_modules/@angular-devkit/build-angular/node_modules/webpack/lib/NormalModule.js:755:11)
    at /path/to/openmrs-esm-patient-chart/node_modules/@angular-devkit/build-angular/node_modules/webpack/lib/NormalModule.js:819:5 {
  opensslErrorStack: [ 'error:03000086:digital envelope routines::initialization error' ],
  library: 'digital envelope routines',
  reason: 'unsupported',
  code: 'ERR_OSSL_EVP_UNSUPPORTED'
}

Pour contourner cela:

export NODE_OPTIONS=--openssl-legacy-provider

J’obtiens des erreurs après la mise à jour de @carbon/react

Vous pouvez voir les erreurs suivantes dans le terminal après une mise à jour de @carbon/react:

ERROR in src/components/search-history/search-history.component.tsx:8:3
TS2305: Module '"@carbon/react"' has no exported member 'ModalHeader'.
 
ERROR in src/components/search-history/search-history.component.tsx:9:3
TS2305: Module '"@carbon/react"' has no exported member 'Pagination'.

N’ajoutez pas de contournement global comme declare module "@carbon/react";. Les versions modernes de @carbon/react fournissent leurs propres types, et une déclaration ambiante globale peut masquer de vraies erreurs TypeScript. Vérifiez la version Carbon installée, consultez les notes de version Carbon pour les exports renommés ou supprimés, mettez à jour les imports avec les noms de composants pris en charge, puis réinstallez les dépendances pour que TypeScript résolve les types fournis par le package.

J’obtiens des conflits de merge dans mon fichier yarn.lock

Si le conflit concerne seulement le fichier généré yarn.lock et que vos manifestes de packages sont corrects, régénérez le lockfile depuis votre branche:

git restore --source=HEAD -- yarn.lock
yarn

N’utilisez pas cette commande si vous devez préserver les changements entrants du lockfile sans les régénérer.

Le job verify échoue dans GitHub Actions pour ma PR

Vous avez probablement une erreur de lint ou TypeScript. ESLint est configuré pour échouer lorsqu’il signale des warnings. Lancez yarn turbo lint localement pour voir l’erreur précise dans votre IDE. Pour les erreurs TypeScript, elles devraient apparaître dans le log CI. Sinon, lancez yarn turbo typescript localement.

J’obtiens des erreurs 502 en récupérant la session sur un serveur local

Si vous exécutez un serveur de développement local et obtenez des erreurs 502 en essayant de récupérer la session, le serveur dev3, vers lequel votre serveur local proxifie, est probablement indisponible. Vérifiez d’abord que vous pouvez vous connecter à dev3 . Si ce n’est pas possible, attendez que le serveur revienne.

J’utilise @openmrs/esm-patient-common-lib et j’obtiens “No workspace named ’…’ has been registered”

Cette erreur signifie très probablement que vous devez ajouter @openmrs/esm-patient-common-lib à la liste peerDependencies de votre package.json. Assurez-vous aussi que @openmrs/esm-patient-common-lib: next est présent dans vos devDependencies.

J’obtiens une erreur Oops! An unhandled promise rejection occurred au chargement du serveur de développement

Si vous voyez une erreur Unhandled promise rejection en lançant un serveur de développement ou une instance de production O3, cela signifie souvent qu’un module ne se charge pas correctement. La console devtools du navigateur contiendra probablement un message d’erreur sur le module concerné. Commencez par vérifier qu’il n’y a pas d’overrides obsolètes d’import map ou de routes dans Devtools. Pour corriger l’erreur, ouvrez le panneau Implementer Tools et cliquez sur Reset all overrides. Rechargez ensuite la page. L’erreur devrait disparaître. Vous pouvez aussi inspecter le local storage du navigateur et supprimer les surcharges que vous y trouvez. Rechargez toujours la page après cela.

Je rencontre des problèmes de mémoire en construisant Core

Quand vous testez des changements de Core avec yarn run:shell depuis le dossier esm-core, vous voudrez généralement lancer yarn turbo build pour vous assurer d’exécuter les derniers changements. Vous pouvez rencontrer des erreurs comme celle-ci pendant le build frontend:

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Pour augmenter la limite mémoire du processus Node.js, lancez:

export NODE_OPTIONS=--max-old-space-size=8192

Cette commande augmente la limite mémoire du processus Node.js à 8 Go. Cela peut affecter les performances du système. N’augmentez la limite que si nécessaire.

Nettoyer les fichiers générés peut aussi aider. Utilisez cette option en dernier recours et prévisualisez d’abord ce qui serait supprimé:

git clean -fdxn

La vraie commande de nettoyage supprime les fichiers et dossiers non suivis ou ignorés de votre répertoire de travail, y compris les artefacts de build, les dossiers node_modules et les fichiers temporaires qui causent parfois des problèmes de build. Elle ne réinitialise pas les fichiers suivis, mais elle peut quand même supprimer des fichiers locaux utiles.

git clean -fdx

Ne lancez git clean -fdx qu’après avoir confirmé que la simulation ne contient rien d’important.