Set up Microfrontends served from OpenMRS server

If you're just getting started with OpenMRS SPA, please first set up a local development environment.

Setting up Microfrontends

1. Install openmrs-module-spa on your OpenMRS server
2. Create a directory, in which we will create a packmap package (see the following instructions). You'll probably want to make it a github repository, like this one.
3. In this directory, create a package.json based on the packmap OpenMRS example
4. Create an override-import-map.json file (see the example) with the line
       "@openmrs/esm-root-config": "/openmrs/frontend/@openmrs/esm-root-config@1.1.1/dist/openmrs-esm-root-config.defaults.js"
where 1.1.1 is the version of @openmrs/esm-root-config that you have in your package.json

5. npm install

6. npm run build

7. Symlink* the resultant openmrs/frontend directory into your OpenMRS server's application data directory as "frontend". For my SDK server named "foo", on Linux, I do

     ln -s $(realpath openmrs/frontend) ~/openmrs/foo/frontend

8. Start the OpenMRS server

9. Navigate to localhost:8080/openmrs/spa/login (assuming your server is at localhost:8080)

10. If the page comes up blank...

    1. Open the browser developer console (probably Ctrl+Shift+i)

    2. Work through the errors with the Troubleshooting Guide

At this point, you should have microfrontends working entirely offline!

Adding configuration and assets without a custom root config

If you won't be creating a custom root config, you can configure your application in the following manner

1. Create a directory in your packmap package directory called "assets"
2. Create a config.json file in that directory

3. Add the command*
       ln -s $(realpath assets) openmrs/frontend/ 
to the build script in package.json (separate it from previous commands with a &&)

4. Add the following line to your override-import-map.json

       "config-file": "/openmrs/frontend/assets/config.json"

5. That config file can refer to things you put in that assets directory, which will be served under  localhost:8080/openmrs/frontend/assets/

Developing on modules

TODO

Using a custom root config

Once your root config is published, you can add it to the packmap package like any other module. We want to make the import map point to our module for "@openmrs/esm-root-config". Therefore we will add a line to our import map override:

    "@openmrs/esm-root-config": "/openmrs/frontend/@myorg/esm-root-config@1.0.0/dist/myorg-esm-root-config.js"

*Sorry Windows users. Maybe one of you can fill in the equivalent thing to do here?