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. Click Create a new repository and follow the instructions to create a new repository. Clone the new repository to your local machine. In this case, we'll name the new repository openmrs-esm-active-prescriptions. Click the Create repository from template button and then 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 how runDevelop (opens in a new tab).

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.

Update the route to the frontend module.

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

"$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. Information about that can be found in the Implementer Documentation on Deployment (opens in a new tab).

Set up an instance of O3 Create a distribution