👋 New to our project? Be sure to review the OpenMRS 3 Frontend Developer Documentation. You may find the Map of the Project especially helpful. 🧑🏫
Also see the API documentation
for @openmrs/esm-framework
, which is contained in this repository.
Below is the documentation for this repository.
This is a Lerna project containing the core packages for the OpenMRS Frontend. These packages handle the "cross-cutting concerns" described in the Domain Decomposition document.
This contains tooling and the app shell.
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-breadcrumbs: management of UI breadcrumbs
- @openmrs/esm-config: validation and storage of frontend configuration
- @openmrs/esm-error-handling: handling of errors
- @openmrs/esm-extensions: implementation of a frontend component extension system
- @openmrs/esm-globals: useful global variables and types
- @openmrs/esm-offline: provides offline functionality
- @openmrs/esm-react-utils: utilities for React components
- @openmrs/esm-state: brings in state management
- @openmrs/esm-styleguide: styling and UI capabilities
- @openmrs/esm-utils: general utility and helper functions
All libraries are aggregated in the @openmrs/esm-framework
package:
A set of frontend modules provide the core technical functionality of the application.
- @openmrs/esm-devtools-app
- @openmrs/esm-implementer-tools-app
- @openmrs/esm-login-app
- @openmrs/esm-primary-navigation-app
- @openmrs/esm-offline-tools-app
To set up the repository for development, run the following commands:
yarn install
yarn setup
To build all packages in the repository, run the following command:
lerna run build
Verification of the existing packages can also be done in one step using yarn
:
yarn verify
yarn run:shell
cd packages/apps/esm-[xyz]-app
yarn serve
# Use with [Import Map Overrides](https://openmrs.github.io/openmrs-esm-core/#/getting_started/setup?id=import-map-overrides)
cd packages/tooling/openmrs
yarn build
./dist/cli.js
Run yarn test
in the directory containing the package you want to test.
Run yarn lerna run test
to run all the tests in this repository.
If you want to try out changes to a framework library, you will
probably want to yarn link
or npm link
it into a frontend module.
Note that even though frontend modules import from @openmrs/esm-framework
,
the package you need to link is the sub-library; e.g., if you are trying
to test changes in packages/framework/esm-api
, you will need to link
@openmrs/esm-api
.
To increment the version, run the following command:
yarn release
You will need to pick the next version number. We use minor changes (e.g. 3.2.0
→ 3.3.0
)
to indicate big new features and breaking changes, and patch changes (e.g. 3.2.0
→ 3.2.1
)
otherwise.
Note that this command will not create a new tag, nor publish the packages.
After running it, make a PR or merge to master
with the resulting changeset.
Once the version bump 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
, orlerna publish
. Use the above process.