GitHub: openmrs-esm-module-config

What is this?

openmrs-esm-module-config is the configuration library for OpenMRS microfrontends. It strives to establish configuration as a first-class concern of OpenMRS components. To this end, it provides mechanisms to make configurability easier for developers and configuring easier for implementers.

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": {
    "logo": {
      "src": "https://pbs.twimg.com/media/C1w_czvWgAAWONL.jpg"
    }
  },
  "@openmrs/esm-home": {
    "search": {
      "numResultsPerPage": 20
    }
  }
}

How do I add a configuration file to my OpenMRS implementation?

There are two methods for doing so.

The Simple Way

This is the method to use if you do not have an esm-root-config override. All you need to do is 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. Your import map will then look like

{
  "imports": {
    ...
    "config-file": "/openmrs/frontend/config.json"
    ...
  }
}

The Flexible Way

This method requires you have an esm-root-config override. This allows you to have multiple configuration files, which will be merged together in an order that you specify. You add your configuration files to your root override module, import them, and provide them to esm-module-config. All this must happen before you register your applications.

Example code:

import { provide } from "@openmrs/esm-module-config";

import pihConfig from "./pih-config.json";
import pihMexicoConfig from "./pih-mexico-config.json";

provide(pihConfig);
provide(pihMexicoConfig);

All provided configs will be merged, with elements provided by later calls to provide taking priority. The import map config file, config-file, will also be merged, and will take the lowest priority. In the above example, configuration elements in pih-mexico-config.json will take priority over those in pih-config.json.

You can break up your configuration files into hierarchies, or per module, or per groups of modules.

I'm developing an ESM module. How do I make it configurable?

You should use this module, esm-module-config, to make your modules configurable. Getting set up is easy.

Defining a schema

You need to tell esm-module-config what configuration files for your module should look like. You will also provide defaults for all of the values — in OpenMRS ESMs, all configuration is optional.

import { defineConfigSchema } from "@openmrs/esm-module-config"

defineConfigSchema("@openmrs/esm-hologram-doctor", {
  hologram: {
    color: {
      default: false
    }
  },
  virtualProvider: {
    name: {
      family: {
        default: "Kenobi"
      }
    }
  }
})

Using config values

In React

The moduleName provided to the openmrsRootDecorator is used to look up the configuration elsewhere in the application. So in the example above, the root decorator call would look something like

export default openmrsRootDecorator({
  featureName: "hologram doctor",
  moduleName: "@openmrs/esm-hologram-doctor"
})(Root)

given an application root component named Root.

You can then get the config tree as an object using the useConfig React hook.

import { useConfig } from "@openmrs/esm-module-config"
                                                       
export default function DoctorGreeting() {     
  const config = useConfig()
  const greeting = "Hello, my name is Dr. " + config.virtualProvider.name.family
  return (
    <div>{ greeting }</div>
  )
}

The content of config will be pulled from the config files, falling back to the defaults for configuration elements for which no values have been provided.

In Angular, Svelte, or something else

This hasn't been implemented yet, but we would like to implement it! Please reach out to bistenes@pih.org and/or open an issue on the OpenMRS Jira.