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 managing referrals. 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-referrals-queue. Click the Create repository from template button and then clone the new repository to your local machine.

Step 2

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 referrals-queue.
Rename the files with hello in their name to root. For example, src/hello/hello.component.tsx should be renamed to src/root/root.component.tsx.
Update the app entry point at src/index.ts as appropriate, including the following:
- Change the moduleName to @openmrs/esm-referrals-queue.
- Change the featureName from hello-world to a blank string. You'll change this to a more useful value later on.
- Rename the hello export to root.
- Remove the redBox, blueBox and brandBox named exports.
Next, in the routes.json file, replace the value of the extensions with an empty array and then replace the contents of the pages array with the following:
```
{
  // ...
  "extensions": [],
  "pages": [
    {
      "component": "root",
      "route": "root"
    }
  ]
}
```
This configuration makes it so that navigating to the root route loads the component exported by the root named export.
Next, delete the boxes, greeter and patient-greeter directories.
Next, replace the contents of your app's configuration schema (in config-schema.ts) with the following:
```
import { Type, validator } from "@openmrs/esm-framework";
 
export const configSchema = {};
 
export type Config = {};
```
You can tweak this file later on to add your own configuration options.
Delete the translation keys and strings in translations/en.json.
Replace all instances of hello with root, and Hello with Root.
Amend the contents of the test file at root.test.tsx to use an empty configuration schema.
Amend root.component.tsx as follows:
- Rename the default exports from Hello to Root.
- Remove the Boxes, Greeter, and PatientGetter imports.
- Replace the contents of the <div> with <p>Referrals Queue goes here</p>.

Step 3

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

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 for 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).

Setting up an instance of O3 Creating a distribution