Wiki Spaces


Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack


Page tree
Skip to end of metadata
Go to start of metadata

This documentation is intended to enable administrators, implementers, and developers to set up and configure an OpenMRS Frontend 3.0 application. If you haven't read the Project Overview yet, do that first.

Notes for developers only are in Info boxes like this. Non-developers do not need to worry about this information.


OpenMRS Frontend 3.0 uses microfrontends. A microfrontend is a self-contained piece of application. It has some UI, and some ideas about where in the application it should be rendered. Each microfrontend can be configured, and some aspects of how microfrontends interact can be configured, too.

There are four important pieces of the OpenMRS Microfrontends system:

  • The app shell, which is the "base" of the application and coordinates everything
  • The framework, which is a library that all microfrontends use
  • The import map, which is a file that tells the app shell what microfrontends to use and where they are
  • The microfrontends, from which the interface is composed
Each microfrontend is an NPM package with a name ending in -app.


Building the application

An OpenMRS Frontend 3.0 application is built using the frontend tooling, npx openmrs. The resulting files can be served from any file server, or from the OpenMRS server itself.

The following command will build the app shell. This includes the framework, as well as the index.html file which will serve as the entrypoint to your application.

npx openmrs build

Remember that many commands will provide helpful information when run with the --help flag. The various features of npx openmrs offer command line flags that you can use to get the application set up according to your needs. Try the following command, for example:

npx openmrs build --help

At this point we still need an import map and the microfrontends. There are two options for going forward.

Serving the whole application from the same place

In most cases, we will want to package the whole application and serve it together. We can assemble an import map and microfrontends using the following command:

npx openmrs assemble

At this point, you should have an application that you can serve.

Serving microfrontends from a CDN

In some cases, you may want to have your import map refer to microfrontends that are located elsewhere, such as in a CDN server. In this case, you will need to assemble your import map manually. Run npx openmrs assemble so that you have an idea of what the import map should generally look like. The entries of your import map, however, will have values that refer to remote places where the package is served. An example line might be

"@openmrs/esm-login-app": ""

Note that you should not use unpkg as your CDN; it is a free service which provides no uptime or support guarantees.

Serving the application

Once you have your application files together, you will need to serve them from somewhere. You can technically serve them from anywhere—from a simple file server or a docker container. One option is to serve these files using the OpenMRS server itself, using the OpenMRS SPA Module.

Using the OpenMRS SPA Module

Install the SPA module as you'd install any other module. Then drop your OpenMRS Frontend 3.0 application files into the frontend subdirectory of the OpenMRS server's application data directory. So on an SDK server called "narnia" on a *nix computer, you would put the files in ~/openmrs/narnia/frontend/ . On a Tomcat server, the files would go in ~tomcat7/.OpenMRS/frontend/ . If you then start this server on port 8080 and navigate to http://localhost:8080/openmrs/spa/login , the SPA Module will attempt to serve the file at frontend/index.html . The "login" part of the path doesn't matter—in a SPA like OpenMRS Microfrontends, the index.html file is always served, and handling the specific route is left to the application itself.

Adding Microfrontends to a distribution

Microfrontends can be added to a distribution's openmrs-distro file.

Configuring the application

What does an OpenMRS frontend configuration file look like?

OpenMRS frontend configuration files are JSON files containing module names as top-level elements. All configuration elements are optional. The available configuration elements for each module should be documented in the module’s wiki page.

Here’s an example!

  "@openmrs/esm-login-app": {
    "logo": {
      "src": ""
  "@openmrs/esm-home-app": {
    "buttons": {
      "enabled": false

Alternatively you can provide your config file as a JavaScript file. It will look just about the same, but with some magic words at the beginning:

exports = {};
exports.default = {
  "@openmrs/esm-login-app": {
    logo: {
      src: ""
  "@openmrs/esm-home-app": {
    buttons: {
      enabled: false

How do I configure my OpenMRS implementation?

There are three methods for doing so.

The recommended way

You can pass configuration files to the build tool npx openmrs build. Run npx openmrs build --help for details. The files will be built into your application directly.

All configs provided in this way will be merged, with subsequent arguments taking priority. You can break up your configuration files into hierarchies, or per module, or per groups of modules.

At runtime via the import map

If, for whatever reason, you aren’t able to provide your config files at application build time, you can provide a single config file at runtime using the import map. Upload your configuration file and add its URL to your import map as a module named config-file. If you are serving your microfrontends from your OpenMRS server, you can simply add your config file to your server’s frontend/ directory. Then your import map will have a line like the one shown below.

  "imports": {
    "config-file": "/openmrs/spa/config.js[on]"

Note that a config file provided in this way will always take priority over other config files (but not the temporary config provided by the Implementer Tools).

A not recommended way

It’s very unlikely that you’ll need to do this, but you can provide config files programmatically by calling the provide function directly. To do this you need to add a simple custom module to your distribution. Its name should be suffixed with -app.

If you think you need to use this mechanism, first ask in the #microfrontends channel on Slack or in Teams. There’s almost certainly a better way.

A microfrontend should absolutely never provide a config file.

You add your configuration files to this module, import them, and provide them to the framework.

Adding your own branding

Using the Implementer Tools

  • No labels