Migrer vers Core v6

Ce guide concerne la migration des modules frontend vers Core v6 et supérieur. Les changements de ce guide correspondent à cette pull request , qui a été publiée pour la première fois sous openmrs@6.3.1-pre.2986.

Pour déterminer quelle version de l’outillage ou du framework Core vous utilisez, exécutez :

yarn why openmrs
# ou
yarn why @openmrs/esm-framework

Si vous utilisez déjà Core v6 ou supérieur, vous n’avez pas besoin de migrer. Sinon, lisez la suite pour apprendre comment migrer.

Contexte : Pourquoi cette migration était nécessaire

Core v5 souffrait d’un problème critique du système de build : les builds séquentiels ralentissaient considérablement ou échouaient complètement en raison de l’épuisement de la mémoire. Cela rendait les workflows de développement peu fiables et forçait les développeurs à utiliser des contournements comme vider les caches entre les builds ou redémarrer les processus Node.

Suite à la version v3.4.0 , nous avons entrepris une mise à niveau majeure de l’outillage qui a abouti à cette PR . Cela représente un changement fondamental dans la façon dont nous construisons, exécutons et testons les modules frontend sous O3.

Core v6 résout ces problèmes grâce à deux changements architecturaux majeurs :

1. Architecture ES Module avec des builds plus légers (couvert dans ce guide)
2. Migration du système de build Rspack pour l’outillage Core (5-10x plus rapide que Webpack)

Introduction

Core v6 introduit une refonte architecturale significative axée sur des builds fiables et des améliorations de performance spectaculaires. Cette mise à jour restructure les packages du framework pour utiliser les modules ES nativement, divise les packages API pour un meilleur tree-shaking et migre l’outillage Core vers des standards modernes.

Les améliorations clés incluent :

• Builds séquentiels fiables – élimine les problèmes de mémoire qui causaient des échecs de build.
• Outillage Core 5–10× plus rapide grâce à la migration Rspack pour le système de build.
• Temps de build ~3× plus rapides pour les applications (builds en moins d’une minute).
• Taille de bundle 51% plus petite – réduction de 6,37 Mo de la taille totale du framework.
• Meilleure performance TypeScript – utilise des fichiers .d.ts générés au lieu d’analyser le TypeScript source.
• Architecture ESM moderne – support natif des modules ES avec un meilleur tree-shaking et des limites d’import plus claires pour les applications.
• Structure de package améliorée – séparation plus claire des API Core et au niveau de l’application, la plupart du code de l’application importe maintenant depuis @openmrs/esm-framework.
• Chemin d’outillage plus clair – cette migration prépare les modules à la migration suivante vers Rspack et Vitest, qui donne une exécution des tests plus rapide et une meilleure compatibilité ESM.

Pour tirer parti de ces améliorations, vous devrez migrer vos modules frontend existants vers cette version pré-release de Core ou supérieure. Ce guide vous guidera tout au long du processus.

Étapes de migration

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

yarn up @openmrs/esm-styleguide@next

yarn up @carbon/react@^1.83.0 webpack@^5.99.9 webpack-cli@^6.0.1 webpack-dev-server@^5.2.1

fnm install 24
fnm use 24

nvm install 24
nvm use 24

module.exports = {
  transform: {
    "^.+\\.tsx?$": ["@swc/jest"],
  },
  // ... reste de la config
};

module.exports = {
  transform: {
    "^.+\\.m?[jt]sx?$": ["@swc/jest"],
  },
  // ... reste de la config
};

module.exports = {
  transformIgnorePatterns: ["/node_modules/(?!@openmrs)"],
  // ... reste de la config
};

module.exports = {
  transformIgnorePatterns: ["/node_modules/(?!@openmrs|.+\\.pnp\\.[^\\/]+$)"],
  // ... reste de la config
};

module.exports = {
  moduleNameMapper: {
    "@openmrs/esm-framework": "@openmrs/esm-framework/mock.tsx",
    // ... autres mappings
  },
};

module.exports = {
  moduleNameMapper: {
    "@openmrs/esm-framework": "@openmrs/esm-framework/mock",
    // ... autres mappings
  },
};

Si vous avez suivi toutes les étapes ci-dessus, vous devriez utiliser les dernières versions des dépendances Core, Carbon et Webpack. Ensuite, nous devrons passer par les vérifications de cohérence suivantes pour nous assurer que tout fonctionne comme prévu :

• Exécuter les tests : yarn test
• Exécuter un build de développement : yarn start
• Exécuter un build de production : yarn build

Si vous obtenez des erreurs, consultez la section Dépannage ci-dessous. Vous pouvez signaler des bugs sous cette épique Jira .

Dépannage

J’ai récupéré les derniers changements mais je ne peux pas faire fonctionner un serveur de développement local

Si vous avez récupéré les derniers changements et que le serveur de développement ne démarre pas, assurez-vous d’exécuter yarn pour installer les dernières dépendances. La nouvelle architecture nécessite des dépendances peer mises à jour.

Je reçois une erreur SyntaxError: Unexpected token 'export' liée aux modules ES

Cela signifie que Jest ne transforme pas correctement les modules ES du framework. Assurez-vous que vos transform et transformIgnorePatterns sont configurés correctement. Voir la section Mettre à jour la configuration Jest ci-dessus pour plus de détails.

Je reçois des erreurs comme Cannot find module 'vitest' ou des erreurs d’import de module ES dans mes tests

Si vous rencontrez des erreurs comme Cannot find module 'vitest' ou des erreurs d’import de module ES dans vos tests :

• Assurez-vous que tous les packages @openmrs/* et openmrs sont mis à niveau vers les dernières versions next : yarn up --fixed '@openmrs/*@next' openmrs@next.

Je reçois une erreur Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported lors de l’exécution d’un serveur de développement

Si vous obtenez l’erreur suivante :

Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported.
Instead change the require of index.js ... to a dynamic import() which is available in all CommonJS modules.

lors de l’exécution d’un serveur de développement, cela signifie que Node.js refuse de charger un module ES (.mjs ou type: “module”) en utilisant require(). CommonJS (require()) et ES Modules (import) sont des systèmes différents. Node.js ne vous permet pas d’utiliser require() pour charger un module ES sauf si vous utilisez Node.js v22.12.0+  avec la nouvelle fonctionnalité expérimentale activée. Vous pouvez corriger cela en mettant à jour votre version Node.js vers v22 ou supérieure; préférez la ligne LTS active, Node v24, pour les nouveaux environnements locaux.

Voir la section Mettre à jour la version Node.js ci-dessus pour plus de détails.

Mes tests échouent avec des erreurs liées aux mocks

Le framework utilise maintenant des fichiers mock différents pour différents environnements. Si vous voyez des échecs liés aux mocks, assurez-vous d’utiliser le bon chemin d’import mock :

'@openmrs/esm-framework': '@openmrs/esm-framework/mock'

Avantages de performance

Après la migration vers Core v6, vous devriez voir :

• Builds fiables : Plus de problèmes de mémoire ou d’échecs de builds séquentiels
• Builds plus rapides : Temps de build en moins d’une minute dans la plupart des cas
• Bundles plus petits : Réduction d’environ 50% de la taille du bundle du framework
• Meilleure expérience de développement : Rechargement à chaud plus rapide et serveurs de développement plus réactifs
• CI/CD amélioré : Exécution de tests et processus de build plus rapides

Exemples de migration

Pour voir des exemples de la façon dont les modules frontend ont été migrés vers Core v6, consultez ces pull requests récentes dans l’écosystème OpenMRS :

• Admin tools 
• Billing 
• Cohort builder 
• Dispensing 
• Fast data entry 
• Form builder 
• Laboratory 
• Patient chart 
• Patient management 
• React form engine 
• Stock management 
• Template 
• User onboarding 

Détails techniques

Cette section explique le “pourquoi” derrière les exigences de migration de Core v6. Si vous avez juste besoin de faire fonctionner votre application, le guide principal ci-dessus couvre tout ce dont vous avez besoin. Si vous êtes intéressé par les détails techniques, lisez la suite.

Vue d’ensemble : Des sources TypeScript aux modules ES

Core v6 a fondamentalement changé la façon dont le framework est construit et distribué. Voici ce que cela signifie en pratique :

Avant (Core v5 et antérieur)

Lorsque vous importiez depuis le framework, vous obteniez des fichiers TypeScript bruts :

import { openmrsFetch } from "@openmrs/esm-framework";
// ↳ Ceci importait des fichiers source .ts réels
// ↳ Votre build devait compiler notre TypeScript à chaque fois
// ↳ Builds plus lents, bundles plus grands

Après (Core v6)

Maintenant vous obtenez des modules ES pré-compilés avec des définitions de type séparées :

import { openmrsFetch } from "@openmrs/esm-framework";
// ↳ Ceci importe des fichiers .js compilés + types .d.ts
// ↳ Votre build ignore la compilation de notre code
// ↳ Builds beaucoup plus rapides, bundles plus petits

Pourquoi c’est important : Votre compilateur TypeScript fait maintenant 50-70% moins de travail car il n’a pas à recompiler tout le framework à chaque build.

Performance : Les chiffres derrière les améliorations

Les changements architecturaux apportent des gains de performance mesurables :

Comment nous avons obtenu ces améliorations

Builds fiables :

• Éliminé les problèmes d’épuisement de mémoire  qui affligeaient Core v5
• La migration Rspack fournit une amélioration de performance de 5-10x pour l’outillage Core
• Meilleure gestion des ressources et traitement parallèle

Builds plus rapides :

• Le compilateur TypeScript utilise des fichiers .d.ts pré-générés au lieu d’analyser le code source
• Éliminé la surcharge de résolution de dépendances circulaires
• Meilleur caching avec les imports de modules ES

Bundles plus petits :

• Le tree-shaking fonctionne maintenant correctement (les modules ES permettent l’analyse statique)
• Divisé les gros packages en packages plus petits et ciblés
• Supprimé le code dupliqué qui était bundlé plusieurs fois

Meilleure performance d’exécution :

• Le chargement des modules à la demande introduit par Core v5 reste en place, et Core v6 réduit le code framework que chaque build d’app doit transformer
• Les bundlers consomment des packages framework compilés et des fichiers .d.ts au lieu de recompiler les sources TypeScript du framework dans chaque build d’app
• Taille de bundle réduite et moins de travail framework au chargement initial de la page

Évolution du système de build : Webpack vers Rspack

Core v6 résout les problèmes fondamentaux du système de build qui affectaient Core v5 :

Le problème avec Core v5

• Les builds séquentiels ralentissaient progressivement ou échouaient complètement
• Épuisement de la mémoire causant des crashes des processus Node
• Contournements manuels requis comme vider les caches entre les builds
• Workflows de développement peu fiables qui frustraient les développeurs

La solution Rspack

• Bundler basé sur Rust avec traitement parallèle natif
• Amélioration de performance de 5-10x par rapport à Webpack
• API compatible - utilise le système de plugins et le format de config de Webpack
• Prêt pour la production - alimente les builds pour TikTok, Miro et Alibaba
• Support natif des modules ES dès le départ

Vous pouvez tester les performances du nouveau système de build en exécutant :

yarn turbo build --force
yarn turbo build --force # Tester les builds séquentiels sans le cache turbo

Architecture des packages : Pourquoi vos imports ont changé

Nous avons réorganisé les packages du framework pour être plus modulaires et efficaces. Nous avons également modernisé la façon dont les packages exposent leur fonctionnalité :

Nettoyage des packages du framework

• Avant : Imports profonds comme @openmrs/esm-framework/src/internal/utils
• Après : API publique propre via le champ exports approprié
• Avantage : Meilleur support TypeScript, limites plus claires, maintenance plus facile

Tests : Pourquoi votre config Jest a besoin de mises à jour

Core v6 adopte les modules ES, avec lesquels Jest a historiquement eu des difficultés. Voici comment nous l’avons résolu :

Le système de mock dual

Le framework expédie maintenant deux ensembles de mocks :

@openmrs/esm-framework/
├── mock.tsx        # Pour les modules ES (Vitest, Jest moderne)
├── mock-jest.tsx   # Pour CommonJS (Jest traditionnel)
└── package.json   # Choisit automatiquement le bon

Lorsque vous importez @openmrs/esm-framework/mock, le framework vous donne automatiquement la bonne version en fonction de la façon dont vous l’importez.

Le framework Core utilise maintenant Vitest

Nous avons migré le framework lui-même de Jest vers Vitest car :

• Support natif des modules ES - pas de configuration complexe nécessaire
• Exécution de tests plus rapide - construit sur le bundling rapide de Vite
• Meilleure expérience développeur - messages d’erreur plus clairs

Vos applications peuvent toujours utiliser Jest ! Les mises à jour de configuration Jest dans ce guide assurent la compatibilité avec notre nouvelle architecture de modules ES.

Mises à jour du système de build : Outillage moderne

Modernisation Sass

• Nouveau : sass-embedded avec API de compilateur moderne
• Ancien : node-sass legacy (déprécié)
• Avantage : Compilation CSS plus rapide, meilleurs messages d’erreur

Évolution Webpack

• Résolution de modules : Mise à jour pour les modules ES
• Traitement CSS : Pipeline amélioré pour les styles du framework
• Développement : Meilleur rechargement à chaud et source maps

Stratégie de migration : Équilibrer le changement et la stabilité

Approche de compatibilité arrière

Nous avons conçu la migration pour être incrémentale, pas disruptive :

✅ Ce qui reste identique :

• Vos API de composants fonctionnent sans changement
• Les modèles de configuration sont identiques
• Le workflow de développement reste familier

⚠️ Ce qui nécessite des mises à jour :

• Configuration de build (Jest, Webpack)
• Versions de packages et imports
• Configuration de compilation TypeScript

Support des navigateurs et environnements

• Navigateurs modernes : Le support natif des modules ES assure des performances optimales.
• Anciens navigateurs : La transpilation automatique est fournie, donc votre application reste compatible même si le navigateur ne supporte pas entièrement les modules ES.
• Node.js : Vous devez utiliser Node.js v22 ou supérieur pour le développement et les builds avec Core v6 et supérieur. Préférez Node v24 pour les nouveaux environnements locaux, car c’est la ligne LTS active depuis mai 2026. Voir la section Mettre à jour la version Node.js ci-dessus pour plus de détails.
• Note sur le bundling du framework : Bien que les composants du framework soient distribués comme modules ES (ESM), les navigateurs utilisent en fait des ESM émulés sous le capot. Cela signifie que vous obtenez les avantages du chargement de modules moderne, mais avec une compatibilité pour une large gamme d’environnements.

Pourquoi cette migration est importante à long terme

Il ne s’agit pas seulement de performance aujourd’hui—il s’agit de positionner le framework pour l’avenir :

• Expérience développeur : Des builds fiables et des boucles de retour plus rapides signifient des développeurs plus heureux et plus productifs.
• Santé de l’écosystème : Les modules ES modernes fonctionnent mieux avec l’écosystème JavaScript plus large.
• Maintenabilité : Une architecture plus propre facilite l’ajout de fonctionnalités et la correction de bugs.
• Budget de performance : Des bundles plus petits laissent plus de place pour les fonctionnalités de votre application.

Le travail de migration que vous faites maintenant paie des dividendes en cycles de développement plus rapides, processus de build fiables et meilleures expériences utilisateur à l’avenir.

Qu’est-ce qui vient ensuite ?

Cette page Core v6 est un guide de migration historique pour les modules qui doivent encore passer de l’outillage de l’ère Core v5 aux packages framework en modules ES. La plupart des modules frontend O3 actifs ont depuis terminé les migrations suivantes vers Rspack et Vitest.

Statut actuel de l’écosystème :

• L’outillage Core et l’outillage d’app O3 par défaut utilisent maintenant Rspack.
• Les monorepos frontend actifs comme Patient Chart et Patient Management utilisent Rspack et Vitest, avec de petites exceptions legacy indiquées dans leurs configs.
• Webpack et Jest restent utiles comme ponts de migration pour les modules qui n’ont pas encore migré, mais ne sont plus le point de départ recommandé.
• Les nouveaux modules devraient démarrer avec la recette Créer un module frontend, qui génère la configuration Rspack et Vitest actuelle avec npm create @openmrs/o3-app@latest.

Après cette migration Core v6, continuez avec Migration vers Rspack et Vitest, sauf si votre dépôt a déjà terminé ce travail.