How openmrs/openmrs-esm-core works
Project Type and Purpose
• This is a Yarn-workspaces monorepo (“openmrs-esm-core”) that provides the core frontend framework, tooling, and a set of React-based microfrontends (apps) for the OpenMRS 3 frontend.
• It’s structured as:
• Core “framework” libraries for configuration, state, routing, API, offline support, extension system, styleguide, etc.
• An “app shell” that boots the SPA, implements the plugin/extension model, service worker, import-map/dynamic loading via Webpack Module Federation.
• A set of standalone “frontend modules” (login, primary navigation, devtools, help menu, implementer tools, offline tools) that the shell loads at runtime.
• CLI tooling for building, developing, and releasing modules.
File-Structure Analysis
• Top-level:
• package.json, yarn workspaces, Turbo repo config
• /packages/tooling: CLI and webpack config generators
• /packages/shell/esm-app-shell: the host application shell with service-worker and dynamic remote loader
• /packages/framework/esm-*: ~15 shared libraries (API, config, context, dynamic-loading, error-handling, extensions, feature-flags, globals, navigation, offline, react-utils, routes, state, styleguide, translations, utils); all aggregated by @openmrs/esm-framework
• /packages/apps: React “microfrontends” (each with its own webpack config, routes.json, translations)
• e2e/: Playwright tests and Docker setups
• .github/workflows, CI, code-ql, bundle-size, e2e, docs
README Insights
• Enumerates the purpose of each package (API helpers, module config, AppContext, dynamic loading, error-handling, etc.).
• Describes the development flow: building all packages, running app-shell, developing apps against local core via yarn link/yalc, and test commands (unit via Turbo, E2E via Playwright).
• Emphasizes the plugin/extension system and Webpack Module Federation dynamic remotes.
1. Developer Tooling & CI/CD
– Turbo repo (yarn workspaces)
– CLI (packages/tooling/openmrs)
– GitHub Actions (build, verify, docs, e2e)
2. Monorepo Packages
– Framework Libraries (@openmrs/esm-api, esm-config, …, esm-utils)
– App Shell (@openmrs/esm-app-shell)
– Frontend Modules (@openmrs/esm-login-app, esm-primary-navigation-app, esm-devtools-app, …)
3. Runtime Environment (Browser)
– Service Worker (caching, offline sync)
– Import Map / Dynamic Remote Loader (Module Federation)
– React Context & State (esm-context, esm-state)
– Extension API (esm-extensions)
4. External Services
– OpenMRS Backend (FHIR REST API)
– Translation service or JSON files (@openmrs/esm-translations)
– Shell ↔ Framework libraries (shared code loaded at startup)
– Shell → Frontend Modules (dynamic import at runtime via import-map / module federation)
– Modules → esm-api → OpenMRS backend (HTTP/FHIR calls)
– Service Worker intercepts network requests (offline caching, sync)
– Modules & Shell ↔ esm-config (module and global configuration store)
– Modules & Shell ↔ esm-context & esm-state (global contextual state)
– Modules ↔ esm-extensions (publish and consume extension slots)
– Modules & Shell consume styleguide components (esm-styleguide) and translation libs (esm-translations)
c. Architectural Patterns & Principles:
– Monorepo + Yarn Workspaces + Turbo for dependency graph and caching
– Microfrontend plugin model via Webpack Module Federation dynamic remotes
– Publish-subscribe extension slots for loose coupling between modules
– Single SPA-style shell hosting independently developed React apps
– Service worker for offline support (esm-offline)
– Centralized context/provider pattern for global state and config
d. Key Technologies/Frameworks:
– Yarn Workspaces, TurboRepo
– TypeScript, React
– Webpack Module Federation (dynamic-loading)
– Playwright (E2E), Jest (unit)
– GitHub Actions, Bamboo Docker for e2e
– Service Worker (offline-sync)
– FHIR REST API (OpenMRS backend)