...

npm: @openmrs/esm-module-confg

Maintainer: Brandon Istenes (bistenes@pih.org)

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.

...

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 . 

Start by npm install --save @openmrs/esm-module-config. This is a runtime dependency, so it should be included in your webpack externals.

The main task is to create a config schema for your module. The config schema is what tells esm-module-config config what configuration files should look like, including defaults and validations.

Designing a schema

You'll probably start with some idea of what you want configs for your module should to look like. You will also Try and put yourself in the implementer's shoes an imagine what features they will expect to be configurable, and what they might expect the configuration property to be called. Assume they don't know anything about the internal workings of your module.

By way of example, let's say we're building a module for a virtual provider functionality at a very futuristic hospital. Maybe we want an implementer to be able to write the following in their config file:

"@openmrs/esm-hologram-doctor": {
  "hologram": {
    "color": true
  },
  "virtualProvider": {
    "name": {
      "given": ["Qui", "Gon"]
    }
  },
  "robots": [
    { "name": "R2-D2", "homeworld": "Naboo" },
    { "name": "BB-8", "homeworld": "Hosnian Prime" }
  ]
}

In the following section, we'll see how to write a config schema that supports these config elements.

Defining a schema

We'll start with just that first nested config element from above, hologram.color. We must provide defaults for all of the values — in OpenMRS ESMs, all configuration is optional.

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

defineConfigSchema("@openmrs/esm-hologram-doctor", {
  hologram: {
    color: {
      default: false,
      validators: [validators.isBoolean]
  
 }   }
}

The above would expect a configuration file structured like

{
  "@openmrs/esm-hologram-doctor": {
    "hologram: {
      "color": true
   
}
  }
}

Note that each configuration element should have an object for a value, and that this object must define the default for that element. Do not do this:

...

robot: {
  name: {
    default: "R2D2",
    validators: [
      validators.isString,
      validator(n => /\d/.test(n), "all robots must have numbers in their names")
    ]
  }
}

(note that this piece of schema is not part of our above example – it only supports a single robot, whereas we need to allow the implementer to provide an array of robots).

A validator can be created using the validator function, as above.

...