Creating a frontend module

The Template (opens in a new tab) frontend module can be used as a starting point for creating a new frontend module. To create a new frontend module, you can either fork the Template repository or clone and copy it over to the new repository.

Example: Creating a new frontend module

ℹ️

Note that we're setting this repo up as a polyrepo (opens in a new tab). If you want to create a new frontend module in a monorepo, see the note about monorepos below.

Suppose you want to create a frontend module that provides a UI for displaying the active prescriptions. Our goal is to attempt to recreate the Active Prescriptions (opens in a new tab) tab of the openmrs-esm-dispensing-app (opens in a new tab). The process for doing that would be as follows:

Step 1

Go to the GitHub repository for the Template (opens in a new tab) seed app and click the Use this template button. Choose Create a new repository and follow the instructions to create a new repository. In this case, we'll name the new repository openmrs-esm-active-prescriptions. Once created, clone the new repository to your local machine.

ℹ️

Why the esm prefix? Frontend modules have a convention of being prefixed with esm. See the note about frontend modules.

Step 2

You'll want to cd into your project directory and run yarn up openmrs@next @openmrs/esm-framework@next to update the OpenMRS core libraries. Then run yarn to install the project dependencies.

Run yarn start to get the app running. To run the app in a specific port you can add the suffix --port portNumber to the start command.

The app should automatically open up in your browser, and you can use the below credentials to log in. Username: admin Password: Admin123

Once logged in, you should be redirected to the home page of the dashboard. But, wait a second, what's the fancy home page with the side bar and all the data, and where did the login page come from? You'll notice that the code for the home page and the login page is not actually in your project directory. The home (opens in a new tab) and login (opens in a new tab) are apps of their own.

The data is fetched from the hosted dev server, if you want to connect it to a different backend, you can append the suffix --backend https://your-backend-url to the yarn start command.

TLDR; the yarn start command actually runs openmrs develop which according to some configuration sets it all up (read more about configuration).

ℹ️

To learn more about how openmrs develop works, check out runDevelop (opens in a new tab). Note that the Template repository is already set up for Core v5+ and uses routes.json and startupApp() for module registration. If you're migrating an older module, see the migration guide.

Step 3

Next, we'll follow the steps in the README to adapt the code to our needs. That'll include the following steps:

Replace all instances of template with active-prescriptions.
Update the app entry point at src/index.ts as appropriate, including the following:
- Change the moduleName to @openmrs/esm-active-prescriptions-app.
- Change the featureName from root-world to a blank string. You'll change this to a more useful value later on.
- Ensure you have a startupApp() function that calls defineConfigSchema() if your module has configuration. For Core v5+ modules, this is required for configuration schemas to be registered properly.

Update the route to the frontend module.

We need a route URL to access the frontend module. This is specified in src/routes.json in the pages property. You would see that a component root has the route root, this is our root.component.tsx.

src/routes.json

"$schema": "https://json.openmrs.org/routes.schema.json",
"backendDependencies": {
  "fhir2": ">=1.2",
  "webservices.rest": "^2.24.0"
},
"extensions": [
  {
    "name": "Red box",
    "component": "redBox",
    "slot": "Boxes"
  },
  {
    "name": "Blue box",
    "component": "blueBox",
    "slot": "Boxes"
  },
      {
    "name": "Brand box",
    "component": "blueBox",
    "slot": "Boxes"
  }
],
"pages": [
  {
    "component": "root",
    "route": "active-prescriptions"
  }
]

Now that the route is setup, it can be accessed via http://localhost:8080/openmrs/spa/active-prescriptions, which would show the boilerplate for the template app. The boilerplate has useful resources about key features of the O3 framework that will likely help you in the development of your frontend module. To start changing the template code, you can follow the instructions in the README.md of the template repository (opens in a new tab).

Step 4

Profit! You should now have a custom frontend module that you can use in your OpenMRS application.

Creating a frontend module in a monorepo

The process for creating a new frontend module in a monorepo is nearly identical to the one for creating one in a polyrepo with a few tweaks:

Put the contents of the Template into a new directory under packages/. For our example above, we'd create a new directory called packages/esm-referrals-queue and move the contents of Template into it.
Remove configuration files that are already present at the workspace level. These include files and folders such as .github and .eslintrc.
Remove devDependencies from the new frontend module's package.json which are already in the devDependencies of the package.json at the workspace level.

That's it!

To learn more about what's possible with frontend modules, read the Overview guide.

Integrating your frontend module into your application

Once you've created a frontend module, you'll want to integrate it into your application. There are two steps to doing so.

First, publish your frontend module package to NPM. At the end, your package should be visible on npm.js, such as @openmrs/esm-login-app (opens in a new tab).

Then, you'll need to integrate this package into your distribution. Add your module to the frontendModules object in your distro's spa-assemble-config.json file. For more information, see the Creating a distribution guide and the Configuration overview guide.

Set up an instance of O3 Create a distribution