Some apps have been discontinued others are not actively maintained and, quite honestly, the released versions are quite a bit behind times. If you could share some actual error messages, it might be helpful in hunting things down. We do need some sort of registry of maintained 3.x apps and pointers to those versions.
Yeah, I’m not aware that we’ve documented these values in any obvious place. They are used as parameters to the call to the openmrs build, so the “documentation” for them can be found by running npx openmrs build --help.
The four values that you’ve highlighted are used to provide necessary constants to the app-shell (the core of the 3.x frontend). They are ultimately embedded as constants in the generated index.html page that constitutes the single-page application here. Looking there, I notice that there’s now an offline option which we should also support via the SDK. All of these values are dependent on how things are deployed in your application with sensible defaults (so they aren’t specifically required). Specifically:
spaPath or --spa-path or openmrsPublicPath (default: /openmrs/spa/): This is the URL (usually URL path) where the single-page application can be accessed. If you use the default 3.x RefApp setup, this value should be /openmrs/spa/. If you use module-spa, this should be the context path for your OpenMRS installation ending with /spa. For example, if you were to deploy the OpenMRS WAR file as my-openmrs-instance.war the path would be /my-openmrs-instance/spa/. For most setups using module-spa, though, this should also be /openmrs/spa/. If you have configured things so that the frontend is served from a different URL, you should fill in the URL. Ideally, this path is only a relative path and you have a single host which routes requests to the frontend or backend as appropriate or else you will likely encounters CORS issues.
apiUrl or --api-url or openmrsApiUrl (default: /openmrs/): this is the URL used as the base path to access the OpenMRS backend from the frontend. This should the relative path to wherever OpenMRS is deployed in your application. If you’re using the 3.x RefApp setup, this should always be /openmrs/. If you are using module-spa, this should be whatever the context path for your OpenMRS instance is. Normally, this is /openmrs/, but it can vary depending on the name of the WAR file deployed. E.g., if you deployed OpenMRS as my-openmrs-instance.war, the path should be /my-openmrs-instance/.
configUrls or --config-url or openmrsConfigUrls (default: []): The 3.x frontend is configurable using pretty simple JSON documents to describe how things are configured. This setting should contain a comma-separated list of URLs from which the app-shell should download to gather whatever local configurations you made. Honestly, this one has the most variation in how it is used depending on if your running openmrs build directly, using the SDK or the 3.x RefApp setup. In the 3.x RefApp setup, this value is set to the environment variable $SPA_CONFIG and the startup script will convert this variable from either a comma-separate list of values or a space-separated list of values into an appropriate JS array. If specified in the distro.properties file, this should be a comma-separated list of URLs which will (eventually) be converted into an appropriate array passed to openmrs build. If you run openmrs build directly, you should likely use the --config-url argument once for each configuration file you want to load. The URL here depends on where the configuration file will be accessible from. dev3 and O3, for instance, use a configuration file served from Digital Ocean with the URL “https://spa-modules.nyc3.digitaloceanspaces.com/@openmrs/config/config.json”. There is currently no mechanism I’m aware of for automatically adding such configuration files to be served from a specific location, so the specific URLs used will be highly implementation-specific.
importmap or --importmap and a whole bunch of potential variables (default: importmap.json): this is the path to access the importmap.json generated from the run of openmrs assemble. Normally, this should be the same value specified for spaPath with importmap.json appended to the end (e.g., /openmrs/spa/importmap.json). If for whatever reason you’ve decided to separate out the importmap.json file from the rest of your distribution it should be the URL that the app shell can download the importmap.json file from.
Sorry for the mountain of text… the O3 frontend provides a lot of flexibility with how files are arranged, but this flexibility comes at the cost of a lot of explanations that are dependent on where those files are served in your configuration.
The general rule here would be: if you follow the model implementations using module-spa or the 3.x RefApp, you should not need to set any of these values except configUrls. If you don’t follow the model implementations, hopefully the above can provide you with enough guidance.