👋 New to our project? Be sure to review the OpenMRS 3 Frontend Developer Documentation. You may find the Map of the Project especially helpful.

Also see the API documentation for @openmrs/esm-framework, which is contained in this repository.

Below is the documentation for this repository.

OpenMRS Frontend Core

This is a monorepo 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

Frontend modules

A set of frontend modules 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
yarn setup

Building

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

yarn 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

This will use the built versions of the apps in apps/. Those are built by yarn setup or yarn build:apps, or by running yarn build in the directory for any app.

The frontend modules in apps

cd packages/apps/esm-[xyz]-app
yarn serve
# Use with [Import Map Overrides](https://openmrs.github.io/openmrs-esm-core/#/getting_started/setup?id=import-map-overrides)

The tooling

cd packages/tooling/openmrs
yarn build
./dist/cli.js

The tests

Run yarn test in the directory containing the package you want to test.

Run yarn lerna run test to run all the tests in this repository.

Linking the framework

If you want to try out changes to a framework library, you will probably want to yarn link or npm link it into a frontend module. Note that even though frontend modules import from @openmrs/esm-framework, the package you need to link is the sub-library; e.g., if you are trying to test changes in packages/framework/esm-api, you will need to link @openmrs/esm-api.

In order to get your local version of that package to be served in your local dev server, you will need to link the app shell as well, and to build it.

Example

To set up to develop @openmrs/esm-api in a dev server for the patient chart:

1. In this repository, run yarn link in each of packages/framework/esm-api and packages/shell/esm-app-shell.
2. In packages/shell/esm-app-shell, run yarn build:development --watch to ensure that the built app shell is updated with your changes and available to the patient chart.
3. In another terminal, navigate to the patient chart repository. Execute yarn link @openmrs/esm-api @openmrs/esm-app-shell. Then run your patient chart dev server as usual.

Check your work by adding a console.log at the top level of a file you're working on in esm-api.

Version and release

To increment the version, run the following command:

yarn 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 main 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.