...

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?

...

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 simply by modules or groups of modulesper 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.