walteronoh / openmrs-esm-core

The core modules of the OpenMRS Frontend system

Information for developers about the OpenMRS Frontend system can be found at the following link:

OpenMRS Frontend Developer Documentation

Below is the documentation for this repository.

OpenMRS Frontend Core

This is a Lerna project containing the core packages for the OpenMRS Frontend. These packages handle the "cross-cutting concerns" described in the Domain Decomposition document.

Available Packages

Application

This contains tooling and the app shell.

• openmrs
• @openmrs/esm-app-shell

Framework

The following common libraries have been developed. They may also be used independently of the app shell.

• @openmrs/esm-api: helps make calls to the backend
• @openmrs/esm-breadcrumbs: management of UI breadcrumbs
• @openmrs/esm-config: validation and storage of frontend configuration
• @openmrs/esm-error-handling: handling of errors
• @openmrs/esm-extensions: implementation of a frontend component extension system
• @openmrs/esm-globals: useful global variables and types
• @openmrs/esm-offline: provides offline functionality
• @openmrs/esm-react-utils: utilities for React components
• @openmrs/esm-state: brings in state management
• @openmrs/esm-styleguide: styling and UI capabilities
• @openmrs/esm-utils: general utility and helper functions

All libraries are aggregated in the @openmrs/esm-framework package:

• @openmrs/esm-framework

Microfrontends

A set of microfrontends provide the core technical functionality of the application.

• @openmrs/esm-devtools-app
• @openmrs/esm-implementer-tools-app
• @openmrs/esm-login-app
• @openmrs/esm-primary-navigation-app
• @openmrs/esm-offline-tools-app

Development

Getting Started

To set up the repository for development, run the following commands:

yarn install
yarn setup

Building

To build all packages in the repository, run the following command:

lerna run build

Verification of the existing packages can also be done in one step using yarn:

yarn verify

Running

The app shell and the framework

yarn run:shell

The microfrontends in apps

cd packages/apps/esm-[xyz]-app
yarn start

Version and release

If there are any new packages in the monorepo, first verify that their package.json contains a publishConfig section with "access": "public". Or, if the package should not be published, the package.json should contain the entry "private": true.

To increment the version, run the following command:

yarn ci:release

You will need to pick the next version number. We use minor changes (e.g. 3.2.0 → 3.3.0) to indicate big new features and breaking changes, and patch changes (e.g. 3.2.0 → 3.2.1) otherwise.

Note that this command will not create a new tag, nor publish the packages. After running it, make a PR or merge to master with the resulting changeset.

Once the version bump is merged, go to GitHub and draft a new release. The tag should be prefixed with v (e.g., v3.2.1), while the release title should just be the version number (e.g., 3.2.1). The creation of the GitHub release will cause GitHub Actions to publish the packages, completing the release process.

Don't run npm publish, yarn publish, or lerna publish. Use the above process.

Possibilities

The new architecture offers a couple of interesting possibilities. We go into them one by one.

Proxying OpenMRS Backends

We can now proxy any backend. For instance, using the backend of the demo instance we just run:

npx openmrs debug --backend https://demo.openmrs.org/

There are a couple of interesting public instances:

https://qa-refapp.openmrs.org/
https://demo.openmrs.org/
https://openmrs-spa.org/