npmpackage.info

Gathering detailed insights and metrics for @openmrs/esm-framework

Other packages similar to @openmrs/esm-framework

@openmrs/esm-globals

6.3.0

openmrs-esm-globals provides events, variables, and types which are used throughout the rest of openmrs-esm-core.

@openmrs/esm-config

6.3.0

A configuration library for the OpenMRS Single-Spa framework.

@openmrs/esm-translations

6.3.0

O3 Framework module for translation support

@openmrs/esm-feature-flags

6.3.0

A feature flag system for the OpenMRS Single-Spa framework.

Gathering detailed insights and metrics for @openmrs/esm-framework

@openmrs/esm-framework - 6.3.0 | npmpackage.info

@openmrs/esm-framework

The core modules of the OpenMRS 3.0 Frontend system

6.3.0

NOASSERTION

TypeScript

10.82 MB

5.7

Installations

npm install @openmrs/esm-framework

Developer Guide

BETA

Typescript

No

Module System

CommonJS, UMD

Pull Requests

Open

21

Total

1,418

Closed

145

Merged

1,252

Issues

Open

0

Total

0

Closed

0

Releases

v6.3.0

Updated on May 02, 2025

v6.2.0

Updated on Mar 03, 2025

v6.1.0

Updated on Feb 19, 2025

v6.0.4

Updated on Jan 18, 2025

v6.0.3

Updated on Jan 17, 2025

v6.0.2

Updated on Dec 17, 2024

View All 58 releases

Languages

TypeScript

SCSS

JavaScript

Shell

EJS

Dockerfile

CSS

TypeScript (90.59%)

SCSS (5.67%)

JavaScript (3.05%)

Shell (0.36%)

EJS (0.27%)

Dockerfile (0.06%)

Developer

openmrs

Download Statistics

Total Downloads

Last Day

Last Week

Last Month

Last Year

GitHub Statistics

NOASSERTION License

73 Stars

1,745 Commits

248 Forks

59 Watchers

20 Branches

192 Contributors

Updated on Jul 12, 2025

Maintainers

View All 192 Contributors

Package Meta Information

Latest Version

6.3.0

Package Id

@openmrs/esm-framework@6.3.0

Unpacked Size

10.82 MB

Size

2.49 MB

File Count

170

Published on

May 02, 2025

Total Downloads

Cumulative downloads

Total Downloads

NaN

Last Day

NaN

Compared to previous day

Last Week

NaN

Compared to previous week

Last Month

NaN

Compared to previous month

Last Year

NaN

Compared to previous year

Weekly Downloads

Monthly Downloads

Yearly Downloads

:wave: New to our project? Be sure to review the OpenMRS 3 Frontend Developer Documentation. You may find the Introduction especially helpful.

Also see the API documentation for @openmrs/esm-framework, which is contained in this repository.

Below is the documentation for this repository.

OpenMRS Frontend Core

This is a monorepo containing the core packages for the OpenMRS Frontend. These packages handle cross-cutting concerns such as the configuration and extension systems, the core framework, global state management, the styleguide, and more.

Available Packages

Application

This contains tooling and the app shell.

Framework

The following common libraries have been developed. They may also be used independently of the app shell.

@openmrs/esm-api: helps make calls to the backend
@openmrs/esm-config: validation and storage of frontend configuration
@openmrs/esm-context: provides the AppContext for sharing contextual state across the app
@openmrs/esm-dynamic-loading: provides functionality for dynamically loading frontend modules using Webpack Module Federation dynamic remotes
@openmrs/esm-error-handling: handling of errors
@openmrs/esm-expression-evaluator: provides functions that allow evaluation of user-defined expressions in a way safer than eval()
@openmrs/esm-extensions: implementation of a frontend component extension system
@openmrs/esm-feature-flags: hide features that are in progress
@openmrs/esm-globals: useful global variables and types
@openmrs/esm-navigation: navigation utilities, breadcrumbs, and history
@openmrs/esm-offline: provides offline functionality
@openmrs/esm-react-utils: utilities for React components
@openmrs/esm-routes: provides helper functions for working with routes.json files in O3
@openmrs/esm-state: brings in state management
@openmrs/esm-styleguide: styling and UI capabilities
@openmrs/esm-translations: common translations and utilities
@openmrs/esm-utils: general utility and helper functions

All libraries are aggregated in the @openmrs/esm-framework package:

@openmrs/esm-framework

Frontend modules

A set of frontend modules provide the core technical functionality of the application.

Development

Getting Started

To set up the repository for development, run the following commands:

1yarn
2yarn setup

Building

To build all packages in the repository, run the following command:

1yarn build

Verification of the existing packages can also be done in one step using yarn:

1yarn verify

Running the app shell and the framework

1yarn run:shell

run:shell will run the latest version of the shell and the framework only.

Running the frontend modules in `apps`

1yarn run:omrs develop --sources packages/apps/<app folder>

This will allow you to develop the app similar to the experience of developing other apps.

Running the tooling

1cd packages/tooling/openmrs
2yarn build
3./dist/cli.js

Running tests

Unit tests

To run tests for all packages, run:

1yarn turbo run test

To run tests in watch mode, run:

1yarn turbo run test:watch

To run tests for a specific package, pass the package name to the --filter flag. For example:

1yarn turbo run test --filter="@openmrs/esm-styleguide"

To run a specific test file, run:

1yarn turbo run test -- login

The above command will only run tests in the file or files that match the provided string.

You can also run the matching tests from above in watch mode by running:

1yarn turbo run test:watch -- login.test

To generate a coverage report, run:

1yarn turbo run coverage

By default, turbo will cache test runs. This means that re-running tests without changing any of the related files will return the cached logs from the last run. To bypass the cache, run tests with the force flag, as follows:

1yarn turbo run test --force

E2E tests

To run E2E tests locally, follow these steps:

Start the Development Server

Begin by spinning up a development server for the frontend module that you want to test. Ensure the server is running before proceeding.

Set Up Environment Variables

Copy the example environment variables into a new .env file by running the following command:

1cp example.env .env

Execute Tests

Run the tests with the following command:

1yarn test-e2e --ui --headed

Read the e2e testing guide to learn more about End-to-End tests.

Linking the framework

You probably want to try out your changes to a framework library in a frontend module. Unfortunately, getting a working development environment for this is very finicky. No one technique works for all frontend modules all the time.

Note that even though frontend modules import from @openmrs/esm-framework, the package you need to link is the sub-library; for example, if you are trying to test changes in packages/framework/esm-api, you will need to link that sub-library.

If you're unsure whether your version of a core package is running, add a console.log at the top level of a file you're working on.

Here are the tools at your disposal for trying to get this to work:

Yarn link

This should be the first thing you try. To link the styleguide, for example, you would use

1yarn link ../path/to/openmrs-esm-core/packages/framework/esm-styleguide

This will add a line to the "resolutions" section of the package.json file which uses the portal: protocol. The other protocol is link:. If you need to make changes to the esm-framework package, you will need to link it in as well. However, this does not work as a portal created with the yarn link command. Rather you will want to manually add the line to the resolutions field in the package.json file:

1"resolutions": {
2  "@openmrs/esm-framework": "link:../path/to/openmrs-esm-core/packages/framework/esm-framework"
3}

Yalc

Sometimes, the build tooling will simply not work with yarn link. In this case, you will need to use yalc. Install yalc on your computer with:

1npm install -g yalc

Then, link the repository you are working on. For esm-api, for example, run

1# In this repository
2cd packages/framework/esm-api
3yalc publish
4cd ../../../openmrs-esm-patient-chart  # for example
5yalc link @openmrs/esm-api

In order for patient-chart to receive further updates you make to esm-api, you will need to run yalc push in the esm-api directory and yalc update in the patient-chart directory.

Running with a local version of the core packages

This satisfies the build tooling, but we must do one more step to get the frontend to load these dependencies at runtime.

Here, there are two options:

Method 1: Using the frontend dev server

In order to get your local version of the core packages to be served in your local dev server, you will need to link the tooling as well.

yarn link /path/to/esm-core/packages/tooling/openmrs.

You can try using yalc for this as well, if yarn link doesn't work. Or manually creating a link: resolution in package.json. In packages/shell/esm-app-shell, run yarn build:development --watch to ensure that the built app shell is updated with your changes and available to the patient chart. Then run your patient chart dev server as usual, with yarn start.

Method 2: Using import map overrides

In esm-core, start the app shell with yarn run:shell. Then, in the patient chart repository, cd into whatever packages you are working on and run yarn serve from there. Then use the import map override tool in the browser to tell the frontend to load your local patient chart packages.

Once it's working

Please note that any of these techniques will modify the package.json file. These changes must be undone before creating your PR. If you used yarn link, you can undo these changes by running yarn unlink --all in the patient chart repo.

Version and release

We use Yarn workspaces to handle versioning in this monorepo.

To increment the version, run the following command:

1yarn release [version]

Where version corresponds to:

patch for bug fixes e.g. 3.2.0 → 3.2.1
minor for new features that are backwards-compatible e.g 3.2.0 → 3.3.0
major for breaking changes e.g. 3.2.0 → 4.0.0

Note that this command will not create a new tag, nor publish the packages. After running it, make a PR or merge to main with the resulting changeset. Note that the release commit message must resemble (chore) Release vx.x.x where x.x.x is the new version number prefixed with v.

This is because we don't want to trigger a pre-release build when effecting a version bump.

Once the version bump commit is merged, go to GitHub and draft a new release.

The tag should be prefixed with v (e.g., v3.2.1), while the release title should just be the version number (e.g., 3.2.1). The creation of the GitHub release will cause GitHub Actions to publish the packages, completing the release process.

Don't run npm publish, yarn publish, or lerna publish. Use the above process.

Important Notes About Version Updates

When releasing a new major version (e.g., moving from v6 to v7), you must:

Update all peerDependencies that reference @openmrs/ packages in every package that depends on them
Change the version notation from the current major version to the new one (e.g., from 6.x to 7.x)

Example:

1// Before (during v6)
2"peerDependencies": {
3  "@openmrs/esm-config": "6.x",
4  "@openmrs/esm-utils": "6.x"
5}
6
7// After (for v7)
8"peerDependencies": {
9  "@openmrs/esm-config": "7.x",
10  "@openmrs/esm-utils": "7.x"
11}

This ensures that all packages use compatible versions and breaking changes are properly tracked.

Design Patterns

For documentation about our design patterns, please visit our design system documentation website.

Bumping Playwright

Be sure to update the Playwright version in the Bamboo Playwright Docker image whenever making version changes. Also, ensure you specify fixed (pinned) versions of Playwright in the package.json file to maintain consistency between the Playwright version used in the Docker image for Bamboo test execution and the version used in the codebase.

Pinned-Dependencies

Determines if the project has declared and pinned the dependencies of its build process.

Reason

dependency not pinned by hash detected -- score normalized to 0

Details

Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/bundle-size.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/bundle-size.yml/main?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/bundle-size.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/bundle-size.yml/main?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/bundle-size.yml:26: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/bundle-size.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/ci.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:27: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/ci.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:34: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/ci.yml/main?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:44: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/ci.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:64: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/ci.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:66: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/ci.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:73: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/ci.yml/main?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:83: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/ci.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:104: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/ci.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:117: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/ci.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:119: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/ci.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:126: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/ci.yml/main?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:154: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/ci.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/code-ql.yml:42: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/code-ql.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/code-ql.yml:46: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/code-ql.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/code-ql.yml:57: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/code-ql.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/code-ql.yml:71: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/code-ql.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/docs.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/docs.yml/main?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/docs.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/docs.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/e2e.yml:26: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/e2e.yml/main?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/e2e.yml:30: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/e2e.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/e2e.yml:57: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/e2e.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/e2e.yml:63: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/e2e.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/e2e.yml:69: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/e2e.yml/main?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/e2e.yml:79: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/e2e.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/e2e.yml:95: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/e2e.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/e2e.yml:110: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/e2e.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/e2e.yml:130: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/e2e.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/e2e.yml:133: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/e2e.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/e2e.yml:139: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/e2e.yml/main?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/e2e.yml:149: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/e2e.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/e2e.yml:161: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/e2e.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/e2e.yml:173: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/e2e.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/e2e.yml:185: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/e2e.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/e2e.yml:202: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/e2e.yml/main?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/e2e.yml:211: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/e2e.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/e2e.yml:216: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/e2e.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tx-pull.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/tx-pull.yml/main?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/tx-pull.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/tx-pull.yml/main?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/tx-pull.yml:33: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/tx-pull.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tx-push.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/tx-push.yml/main?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/tx-push.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/openmrs/openmrs-esm-core/tx-push.yml/main?enable=pin
Warn: containerImage not pinned by hash: e2e/support/bamboo/playwright.Dockerfile:1: pin your Docker image by updating mcr.microsoft.com/playwright:v1.50.1-jammy to mcr.microsoft.com/playwright:v1.50.1-jammy@sha256:8845c40cdade98fd7a6cd32df75bfc234cd52b3278f9cd1f9fe8d6291e48ea03
Warn: containerImage not pinned by hash: e2e/support/github/Dockerfile:2
Warn: containerImage not pinned by hash: e2e/support/github/Dockerfile:17
Info: 0 out of 32 GitHub-owned GitHubAction dependencies pinned
Info: 0 out of 13 third-party GitHubAction dependencies pinned
Info: 0 out of 3 containerImage dependencies pinned

0

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

Score

5.7

/10

Last Scanned on 2025-07-07

The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.

Learn More

Other packages similar to @openmrs/esm-framework

Other packages similar to @openmrs/esm-framework

@openmrs/esm-framework

Installations

Developer Guide

No

CommonJS, UMD

Pull Requests

21

1,418

145

1,252

Issues

0

0

0

Releases

Languages

Developer

openmrs

Download Statistics

GitHub Statistics

Maintainers

Package Meta Information

Total Downloads

NaN

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dependencies

Peer Dependencies

Dev Dependencies

OpenMRS Frontend Core

Available Packages

Application

Framework

Frontend modules

Development

Getting Started

Building

Running the app shell and the framework

Running the frontend modules in apps

Running the tooling

Running tests

Unit tests

E2E tests

Start the Development Server

Set Up Environment Variables

Execute Tests

Linking the framework

Yarn link

Yalc

Running with a local version of the core packages

Method 1: Using the frontend dev server

Method 2: Using import map overrides

Once it's working

Version and release

Important Notes About Version Updates

Design Patterns

Bumping Playwright

10

10

10

10

10

9

9

0

0

0

0

0

0

5.7

/10

Running the frontend modules in `apps`