👋 New to our project? Be sure to review the OpenMRS 3 Frontend Developer Documentation. You may find the Introduction 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-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-feature-flags: hide features that are in progress
• @openmrs/esm-globals: useful global variables and types
• @openmrs/esm-navigation: navigation utilities, breadcrumbs, and history
• @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-translations: common translations and utilities
• @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

run:shell will run the latest version of the shell and the framework only.

Running the frontend modules in apps

yarn run:omrs develop --sources packages/apps/

This will allow you to develop the app similar to the experience of developing other apps.

Running the tooling

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

Running tests

To run tests for all packages, run:

yarn turbo run test

To run tests in watch mode, run:

yarn turbo run test:watch

To run tests for a specific package, pass the package name to the --filter flag. For example, to run tests for esm-patient-conditions-app, run:

yarn turbo run test --filter="esm-patient-conditions-app"

To run a specific test file, run:

yarn turbo run test -- login

The above command will only run tests in the file or files that match the provided string.

You can also run the matching tests from above in watch mode by running:

yarn turbo run test:watch -- login.test

To generate a coverage report, run:

yarn turbo run coverage

By default, turbo will cache test runs. This means that re-running tests wihout changing any of the related files will return the cached logs from the last run. To bypass the cache, run tests with the force flag, as follows:

yarn turbo run test --force

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; for example, if you are trying to test changes in packages/framework/esm-api, you will need to link it:

yarn link path/to/openmrs-esm-core/packages/framework/esm-framework
yarn link path/to/openmrs-esm-core/packages/framework/esm-api

This satisfies the build tooling, but we must do one more step to get the frontend to load these dependencies at runtime.

Here, there are two options:

Method 1: Using the frontend dev server

In order to get your local version of the core packages to be served in your local dev server, you will need to link the tooling as well.

yarn link /path/to/esm-core/packages/tooling/openmrs.

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. Then run your patient chart dev server as usual, with yarn start.

Method 2: Using import map overrides

In esm-core, start the app shell with yarn run:shell. Then, in the patient chart repository, cd into whatever packages you are working on and run yarn serve from there. Then use the import map override tool in the browser to tell the frontend to load your local patient chart packages.

Once it's working

Please note that this will result in entries being added to the package.json file in the resolutions field. These changes must be undone before creating your PR, which you can do by running yarn unlink --all in the patient chart repo.

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

We use Yarn workspaces to handle versioning in this monorepo.

To increment the version, run the following command:

yarn release [version]

Where version corresponds to:

• patch for bug fixes e.g. 3.2.0 → 3.2.1
• minor for new features that are backwards-compatible e.g 3.2.0 → 3.3.0
• major for breaking changes e.g. 3.2.0 → 4.0.0

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. Note that the release commit message must resemble (chore) Release vx.x.x where x.x.x is the new version number prefixed with v.

This is because we don't want to trigger a pre-release build when effecting a version bump.

Once the version bump commit 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.

Design Patterns

For documentation about our design patterns, please visit our design system documentation website.

Bumping Playwright Version

Be sure to update the Playwright version in the Bamboo Playwright Docker image whenever making version changes. Also, ensure you specify fixed (pinned) versions of Playwright in the package.json file to maintain consistency between the Playwright version used in the Docker image for Bamboo test execution and the version used in the codebase.