What is this?

openmrs-esm-root-config is an in-browser javascript module that serves as the single-spa root config for OpenMRS. It is the very first javascript module that is loaded, and controls which other modules are loaded and active for any particular URL.

How do I use it?

openmrs-esm-root-config is available on npm to be downloaded.

Usage (no customization)

To accept all OpenMRS defaults for modules, do the following:

npm install --save @openmrs/esm-root-config. Alternatively, go to https://www.jsdelivr.com/package/npm/@openmrs/esm-root-config?path=dist and download all files from that directory.
Make the file node_modules/@openmrs/esm-root-config/dist/openmrs-esm-root-config.defaults.js available in your import map with the name @openmrs/esm-root-config.

Usage (with customization)

To customize which modules and single-spa applications are used, do the following:

Create a new repo that will be your custom root config. For example, ampath-esm-root-config.
npm install --save @openmrs/esm-root-config. Alternatively, go to https://www.jsdelivr.com/package/npm/@openmrs/esm-root-config?path=dist and download all files from that directory.
Make your repo's bundle available in your import map, with the name @openmrs/esm-root-config.
In your repo's entry file, add the following code:

^{import { registerApplication, start } from 'single-spa';
import { registerAllCoreApplications } from '@openmrs/esm-root-config';}
^{// Get all the core applications
registerAllCoreApplications(); // alternatively: registerAllCoreApplicationsExcept(['@openmrs/esm-login', '@openmrs/esm-devtools'])}

^{// Add your own application
registerApplication('my-custom-app', () => System.import('my-custom-app'), location => location.pathname.startsWith('/custom'))}

^{// start everything up
start();}

API

The following functions are exported from @openmrs/esm-root-config.

registerAllCoreApplications()

registerAllCoreApplications is a function that calls singleSpa.register() for each of the OpenMRS core applications.

Arguments

None

Return value

None (undefined)

Example

^{import { registerAllCoreApplications } from '@openmrs/esm-root-config';

registerAllCoreApplications();}

registerAllCoreApplicationsExcept(applicationNames)

registerAllCoreApplicationsExcept allows you to specify an array of applicationNames that you do not want to be registered from the set of all OpenMRS core applications.

Arguments

applicationNames (required): an array of string names that must correspond with the OpenMRS core applications that you don't want registered.

Return value

None (undefined)

Example

^{import { registerAllCoreApplicationsExcept } from '@openmrs/esm-root-config';

registerAllCoreApplicationsExcept(['@openmrs/esm-login', '@openmrs/esm-primary-navigation']);}

routePrefix(prefix, location)

routePrefix is a utility function that helps you implement single-spa activity functions. The word "route" refers to the browser's url and the word "prefix" refers to a prefix in the pathname.

Arguments

prefix (required): A string that starts with a / character. Any time the browser's url's pathname starts with that url, your application will be active.
location (required): A Location object. You can just pass in the location given to your activity function.

Return value

A boolean that is true when the location matches the prefix, and false otherwise.

Example

See code examples.

^{import { registerApplication } from 'single-spa';
import { routePrefix } from '@openmrs/esm-root-config';

registerApplication('my-custom-app', () => System.import('my-custom-app'), isCustomAppActive);

function isCustomAppActive(location) {
return routePrefix('/custom', location);
}}

routeRegex(regex, location)

routePrefix is a utility function that helps you implement single-spa activity functions. The word "route" refers to the browser's url and the word "prefix" refers to a prefix in the pathname.

Arguments

regex (required). A regular expression that will be matched against the location's pathname.
location (required). A Location object. You can just pass in the location given to your activity function.

Return value

A boolean that is true when the regex matches the location pathname, and false otherwise.

Example

^{import { registerApplication } from 'single-spa';
import { routeRegex } from '@openmrs-esm-root-config';

registerApplication('my-custom-app', () => System.import('my-custom-app'), isCustomAppActive);

function isCustomAppActive(location) {
return routeRegex(/^patient\/.+\/dashboard/, location);
}}