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.

Developers: Once you've followed the steps in this Implementer Guide, you can also see the Developer Guide for more guidance on building with the 3.x tooling.

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

In This Guide: 


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

There are four important pieces of the OpenMRS frontend modules system:

  • The app shell, which is the "base" of the application and coordinates everything
  • The framework, which is a library that all frontend modules use
  • The import map, which is a file that tells the app shell what frontend modules to use and where they are
  • The frontend modules, from which the interface is composed

Each frontend module is an NPM package with a name ending in -app.

Feeling Confused?

A visual map of building a 3.x application is described in more detail in the Dev Guide's Map of the Project.

Looking for a repo?

Github Logo - Free social media iconsSee the Dev Guide's Repositories You Should Know. Github Logo - Free social media icons

Reference Docker Containers

Reference Application Docker containers are available here: 

Deploying Frontend 3.0 with a server distribution

This kind of application is served using the OpenMRS SPA Module. The module that serves the application from the frontend/  directory within the server directory.

The OpenMRS SDK will build the Frontend 3.0 application in the frontend/ directory within the server directory when the distro file contains any frontend modules. The Frontend 3.0 application is installed when  openmrs-sdk:install, openmrs-sdk:deploy, or openmrs-sdk:build-distro are executed. For an example of how to add frontend modules to the distro file, see the file for Reference Application 3.x.

Frontend modules should be specified in the file in the following format:


<version> can be any version number or any tag published for that package in npmjs.

The other properties accepted by the OpenMRS SDK for the frontend application are


These are described in the frontend tool help documentation. Execute

npx openmrs@next --help
npx openmrs@next build --help

to read more about them.

Deploying Frontend 3.0 independently of the server

Building the application

An OpenMRS Frontend 3.0 application is built using the frontend tooling, npx openmrs. This is the same tooling as used by the SDK, described above. 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 frontend modules. 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 frontend modules using the following command:

npx openmrs assemble

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

Serving frontend modules from a CDN

In some cases, you may want to have your import map refer to frontend modules 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 Frontend 3.0, the  index.html  file is always served, and handling the specific route is left to the application itself.

Example Distribution

To create an example distribution using the OpenMRS 3.0 SPA as frontend you'll need to think of three things:

  1. The app shell (namely what settings you'll need to include it)
  2. What frontend modules to include (their names and versions)
  3. The configuration for these frontend modules

The parts of (2) and (3) also flow in directly or indirectly into the settings defined for (1).

Let's start with (1):

  npx openmrs build --spa-path /openmrs/spa/ --api-url /openmrs/ --config-url config.json --importmap importmap.json

Using this command you'll build a new app shell that will be placed at /openmrs/spa/. The OpenMRS API is supposed to be on the same server (at least reachable from the browser) at /openmrs/ (e.g., a call to /openmrs/ws/rest/v1/session yields the session, so /ws is rooted at /openmrs).

The command above also defines two more things: The frontend modules from (3) are determined by an importmap.json which will be available in the same directory as the SPA (i.e., reachable at /openmrs/spa/ from the browser). Likewise, a configuration file is specified; the file config.json will be loaded from the SPA's path, too.

Now that you'll have your files for the app shell its time to look at how to get the remaining ones.

The frontend modules from (2) can be assembled using:

  npx openmrs assemble --mode survey

This will run a command-line survey iterating over all (publicly) available frontend modules. If included, the survey will ask you what version to take.

Once completed, you'll have a valid importmap.json as well as a directory with all files corresponding to the different frontend modules referenced in this importmap.json.

Finally, you'll also need a configuration. Ideally, you can just write some JSON that represents such a configuration, however, in the real world this will not be so easy.

Our recommended approach is to actually start with an empty JSON file just containing {}. With this empty configuration you can fire up your application shell and actually set it all up as you want to. The frontend module @openmrs/esm-implementer-tools-app will help you to do exactly that.

When you completed your customization in the frontend you can download your individual config.json. Now you can put it besides all the other files to complete your own distribution.

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?

You can pass  --config-url  parameters to the build tool  npx openmrs build.

The following command will build an application that looks for config files at the URLs  /openmrs/spa/abc/config.json  and :

 npx openmrs build --config-url abc/config.json --config-url

Config files will be merged, with values from subsequent files overriding those coming previously. For example, if  abc/config.json  has contents

  "@openmrs/esm-login-app": {
    "logo": {
      "src": "",
"alt": "Our beautiful logo" } }

and  has contents

"@openmrs/esm-login-app": {
"logo": {
"alt": "Our all-star logo"

Then the login page will display the logo given by the first config and the alt text given by the second config.

In this way, you can break up your configuration files into hierarchies, per module, per groups of modules, or however else you please.

See  npx openmrs build --help .

  • No labels