openIMIS frontend assembly

running

this repository builds:

• a docker image ghcr.io/openimis/openimis-fe that can be use in a docker compose
• a minified js application that can be served by any webserver (see release)

the build content is defined by the openimis.json file

more information for:

• docker Windows
• docker Linux
• reverse proxy toward other openIMIS services

Developers setup

To start working in openIMIS as a (module) developer:

When programming for openIMIS frontend, the shared (with openimis-fe_js) dependencies (react,...) must be declared as *peerDependencies* in your package.json file. You are also highly encouraged to used the features provided in the openimis-fe-core module. This includes (but is not limited to) main menu entries, date handling, user info,... Another important point is NOT TO HAVE in backend db table user_Core (managed by Django) user called 'admin' or 'Admin'. This could case defects while running frontend via command `yarn start`. This issue is related to the link between userCore and tblUser tables.

• clone this repo (creates the openimis-fe_js directory)
• install node (node V16.x)
• install yarn
• within openimis-fe_js directory
  • generate the openIMIS modules dependencies and locales (from openimis.json config): yarn load-config or yarn load-config openimis.json
  • install openIMIS technical dependencies: yarn install
  • start openIMIS frontend (in development mode): yarn start

To start working in openIMIS as a (module) for production with git / shh / urls for dependencies:

• within openimis-fe_js directory

  • generate the openIMIS modules dependencies and locales (from openimis.json config): yarn load-config or yarn load-config openimis.json
  • clean yarn cache in case local directory / git /link are used: yarn cache clean
  • install openIMIS technical dependencies: yarn install
  • build openIMIS frontend (in development mode): yarn build
  • copy the build folder on the webserver

using npm

```{
	"name": "CoreModule", // If name is not provided, it will assume the module is exported as the `default` module
	"npm": "@openimis/[email protected]"
}```

At this stage, your browser opened on localhost:3000 with current openIMIS frontend. In developement mode, the frontend connects to the backend via a proxy configuration, expecting to reach the backend on localhost:8000 (cfr. /package.json file, "proxy" entry).

To edit (modify) an existing openIMIS module (e.g. @openimis/fe-claim)

• checkout the module's git repo NEXT TO (not within!) openimis-fe_js directory and create a git branch for your changes
• from openimis-fe-claim_js
  • install module dependencies: yarn install
  • build current (dev) version of the module: yarn build
  • prepare a linkable version of your local package: yarn link
• from openimis-fe_js
  • uninstall the packaged module you want to work on (example @openimis/fe-claim): yarn remove @openimis/fe-claim
  • link the local version of the module: yarn link "@openimis/fe-claim"

Note:

• It is not necessary to register a linked module in the package.json file
• To unlink a previously linked package: yarn unlink "@openimis/fe-claim"
• [OPTIONAL] To enable live reload of the module, from openimis-fe-claim_js, activate the watch: yarn start (if configured into the package.json of the module)

To create a new openIMIS module (e.g. @openimis/fe-mymodule)

• create a (git-enabled) directory next to the other modules: /openimis-fe-mymodule_js. Note: the module name can be different from the directory/github repo. The npm repo has an @openimis scope to group all openIMIS modules
• to be integrated in openIMIS ecosystem, you module should provide an entry entity (e.g. MyModule) with its contributions (MainMenu entries,...).
• prepare a linkable version of your local package: yarn link (from within /openimis-fe-mymodule_js)
• from /openimis-fe_js:
  • install the linkable version of your package: yarn link @openimis/fe-mymodule
  • add your module (name and entry entiry) in openimis.json and regenerate the modules import script: node module-requirements.js Note: to ease development lifecycle, please consider using the 'rollup' mechanism (see @openimis/fe-core for an example)

To create a distinct implementation of an existing openIMIS module (e.g. @openimis/fe-location-dhis2)

Unlike backend modules, there is 'shared logical name' between distinct implementations of a same 'module'. If you want to provide an distinct implementation for locations (example), just create a separate module, with a distinct module name and ensure the packaging (distribution) picks your module (and not the reference implementation).

To publish (in npm central repo) the modified (or new) module

• adapt your package.json (bump version number, ensure license is mentioned,...)
• commit your changes to the git repo and merge to master
• tag the git repo according to your new version number
• publish to npm central repo: npm publish (from within /openimis-fe-mymodule_js) Note: you'll need to login,... (cfr. https://docs.npmjs.com/cli/publish)

Distributor setup

Note: As a distributor, you may want to run an openIMIS version without docker. To do so, follow developers setup here above (up to starting the server with yarn start).

To create an openIMIS Frontend distribution

• clone this repo (creates the openimis-fe_js directory) and create a git branch (named according to the release you want to bundle)
• adapt the openimis-fe_js/openimis.json to specify the modules (and their versions) to be bundled
• make release candidates docker image from openimis-fe_js/: docker build . -t openimis-fe-2.3.4
• run the docker image: docker run -p 8080:80 openimis-fe-2.3.4 (exposing the 80 port to 8080 port of docker host)

When release candidate is accepted:

• commit your changes to the git repo
• tag the git repo according to your new version number
• upload openimis-be docker image to docker hub

Note: This image only provides the openimis frontend server. The full openIMIS deployment (with the backend,...) is managed from openimis-dist_dck repo and its docker-compose.yml file.

Developer tools

To download from repository frontend module and build it locally in single command

• from /openimis-fe_js:

  • run this command: node dev_tools/installModuleLocally.js <repourl> <branch>
  • for example node dev_tools/installModuleLocally.js https://github.com/openimis/openimis-fe-contract_js.git develop

• this command executes every steps to install module locally. Those steps are:

  1. Download module from GitHub repository using git clone.
  2. Go into module directory
  3. Within this directory run yarn install , yarn build and yarn link (according to that provided order)
  4. Within openimis-fe_js:

  • execute yarn remove @openimis/fe-invoice

  • In openimis.json openimis add:

    {
      "name": "ContractModule",
      "npm": "@openimis/[email protected]"
    }

  • Edit package.json - in "dependencies" put or update this module that you want to run from local environment:

       {
         ...
         "dependencies": {
             ...
             "@openimis/fe-contract": "file:../openimis-fe-contract_js",
             ...
         }
         ...
       }

  • execute node modules-config.js

  • run yarn link <module> for example: yarn link "@openimis/fe-contract"

  • run yarn install

• after this you can execute yarn start and you should see local module in your imis application.

To add github workflows files to the particular module

• from /openimis-fe_js:
  • run this command: node dev_tools/addCIToModule.js <moduleNameDirectory>
  • for example node dev_tools/addCIToModule.js openimis-fe-invoice_js
• this command allows to add files to execute CI on every PR and allows to publish to npm.
• if .github/workflows doesn't exist in particular module, this directories are created while running this command
• files to be added through that command based on provided templates:
  • CI_and_build.yml
  • npmpublish.yml
• those files are saved in .github/workflows

To fetch all modules and install them from local directories

• from /openimis-fe_js:
  • run this command: node dev_tools/installModuleLocallyAll.js. This command will execute all required steps to fetch all modules present in openimis.json from the git repositories and install them as editable libraries.

Managing translations/localization

To add new translation/localisations:

• create separate new module based on frontend template module.
• this module should be named like: openimis-fe-language_{lang}_js for example openimis-fe-language_es_js (Spanish language)
• add to this module such files as: .babelrc, .gitignore, .estlintrc
• within src/translation add {lang}.json file for example es.json
• in index.js within src modified (for example we want to have 'es' Spanish language):

       import messages_es from "./translations/es.json";

       const DEFAULT_CONFIG = {
           "translations": [{ key: "es", messages: messages_es }],
       }

       export const LanguageEsModule = (cfg) => {
           return { ...DEFAULT_CONFIG, ...cfg };
       }

• build your new module with translations by typing within this module yarn build, yarn install and yarn link commands.
• in tblLanguages on database level add new language for example 'es' (Spanish language)
• within assembly frontend module openimis-fe_js in openimis.json add language key for new language/localization for example:

      ...
       "locales": [
       {
          "languages": [
            "es",
            "es-ES"
          ],
          "intl": "es-ES",
          "fileNames": "es"
       },
       {
          "languages": [
            "en",
            "en-GB"
          ],
          "intl": "en-GB",
          "fileNames": "en"
        },
        {
          "languages": [
            "fr",
            "fr-FR"
          ],
          "intl": "fr-FR",
          "fileNames": "fr"
        }
      ],
      ...

• in openimis.json add also this newly created module with translations
• within openimis-fe_js/src in locales.js add new language like below:

      export const locales = ["es-ES","en-GB","fr-FR"]
      export const fileNamesByLang = {"es":"es", "es-ES":"es","en":"en","en-GB":"en","fr":"fr","fr-FR":"fr"}
      export default {"es":"es-ES", "es-ES": "es-ES","en":"en-GB","en-GB":"en-GB","fr":"fr-FR","fr-FR":"fr-FR"}  

• type yarn build and if success - type yarn start and you should see this translation in your app (go to 'users' page, select user, change language into the newly provided, refresh page and you should see texts in changed language)
• if you encounter any problems by that point, run yarn load-config in the main module
• there is also possibility to overwrite particular language for example 'English' into 'Gambian English' (without changes on database level). In your new translation module in index.js (for example new module called openimis-fe-language_en_gm_js):

      import messages_en from "./translations/en.json";

      const DEFAULT_CONFIG = {
          "translations": [{ key: "en", messages: messages_en }],
      }

      export const LanguageEnGmModule = (cfg) => {
          return { ...DEFAULT_CONFIG, ...cfg };
      }

• this approach overwrites default en language translations into en-gm (Gambian English) translations without adding new language on database level and without changing 'locales' in 'openimis.json' and 'locales.js' file both on assembly frontend module (openimis-fe_js).

Handling errors while running openIMIS app - the most common ones

Handling error with no content display after running frontend

Based on error reported on that ticket

Description of error:

• after yarn start the page loads but no content is display
• sometimes it just keeps spinning the loader
• web console doesn't show any errors

How to solve this?

• double check if you use proper versions of backend/frontend modules (assembly and core ones)
• make sure you have the latest version of dockerized database

Conclusions:

• The reason of this error is usually using not up-to-date assembly and core modules (both backend and frontend ones)

Handling error with 400 error after running frontend

Based on error reported on that ticket

Description of error:

• modular openIMIS deployed on server
• backend is set on port 8000, frontend is set on port 3000
• backend works fine, no errors
• it is not possible to reach both login and home page due to 400 error
• web console doesn't show any errors

How to solve this?

• double check if you use proper versions of backend/frontend modules (assembly and core ones)
• make sure you added env variables on backend side (site root/sire url)
• double check value for proxy key in package.json (IMPORTANT: be careful with this setting on production environment)

Conclusions:

• The reason of this error is usually not setting up env variables on backend side and wrong value for proxy key

How to report another issues?

If you face another issues not described in that section you could use our ticketing site. Here you can report any bugs/problems you faced during setting up openIMIS app.

🎨 Theme & Logo Configuration

To customize the appearance of your openIMIS frontend, you can define a theme and optionally a logo configuration in your module settings either on database level or django admin panel (table moduleConfiguration).

🧹 JSON Configuration Structure

Theme Configuration (theme)

To override the default theme colors, provide a theme object under the fe-core module configuration. Below is the full structure with all supported properties:

{
  "theme": {
    "name": "defaultBlue",
    "primaryColor": "#004E96",
    "errorColor": "#801a00",
    "whiteColor": "#ffffff",
    "backgroundColor": "#e4f2ff",
    "headerColor": "#BCD4E6",
    "greyColor": "grey",
    "selectedTableRowColor": "rgba(0, 0, 0, 0.08)",
    "hoveredTableRowColor": "rgba(0, 0, 0, 0.12)",
    "toggledButtonColor": "#999999",
    "lockedBackgroundPattern": "repeating-linear-gradient(45deg, #D3D3D3 1px, #D3D3D3 1px, #fff 10px, #fff 10px)"
  }
}

Description of Properties:

Property	Description
name	Optional name identifier for the theme
primaryColor	Main brand color used in headers, buttons, text, etc.
errorColor	Used to highlight errors or critical UI elements
whiteColor	Used for contrasting text and background elements
backgroundColor	General background color for the app
headerColor	Header background color
greyColor	Used for subdued UI elements (e.g., disabled text)
selectedTableRowColor	Background for selected table rows
hoveredTableRowColor	Background for hovered table rows
toggledButtonColor	Background for toggled/active state buttons
lockedBackgroundPattern	Background pattern used for locked (readonly) UI elements

Note: If theme is not provided, the default openIMIS theme will be used instead.

---

🖼️ Logo Configuration (logo)

Add additional property under fe-core configuration in moduleConfiguration. Logos can also be configured via base64-encoded images. This allows the UI to show custom branding without bundling new static files.

{
  "logo": {
    "value": "data:image/png;base64,iVBORw0KGgoAAAANSUhEU...",
    "disableTextLogo": true
  }
}

Note: Supported formats: svg+xml, jpeg, png

Logo Fields:

Property	Description
value	Base64-encoded string of the main logo
disableTextLogo	(Optional) Do not show openIMIS text next to logo: true or false. By default false

Note: If logo.value is not provided, the default openIMIS logo will be used instead.

---

✅ Example GraphQL Response from module configuration GQL

{
  "moduleConfigurations": [
    {
      "module": "fe-core",
      "config": "{\"theme\":{...}, \"logo\":{...}}"
    }
  ]
}

Frontend Development Setup with CRACO and API Proxy

This frontend project uses CRACO to customize Create React App configurations without ejecting. It also sets up a flexible proxy system for API routing during development.

🔧 Requirements

• Node.js (v16+ recommended)
• Yarn

📦 Setup

1. Install dependencies:

   yarn install

2. Create .env file (if it doesn't exist):

   API_PROXY_TARGET=http://localhost:8000

   • Use http://backend:8000 if you're running the backend as a Docker container.

3. Start the dev server:

   yarn start

   This will start the frontend on http://localhost:3000/front and proxy all API requests from /api to the API_PROXY_TARGET defined above.

🌐 Proxy Configuration

The proxy logic is handled in src/setupProxy.js. It reads API_PROXY_TARGET from the environment to dynamically redirect API calls to the appropriate backend:

• /api → $API_PROXY_TARGET
• Additional proxies (e.g. /opensearch) are configured statically in package.json:

"proxies": {
  "opensearch": {
    "base": "/opensearch",
    "target": "http://opensearch:5410"
  }
}

⚙️ CRACO Configuration

craco.config.js sets:

• output.publicPath to /front/ to support deployment under sub-paths.
• DefinePlugin to inject environment variables.
• Dev server historyApiFallback and proxy behavior.

webpackConfig.output.publicPath = '/front/';

📁 Folder Structure

• src/setupProxy.js: Middleware proxy setup
• craco.config.js: Webpack and dev server overrides
• .env: Environment-specific overrides

✅ Tips

• Make sure the backend server is running and accessible from your frontend environment.
• Use Docker network names like http://backend:8000 when both frontend and backend are running in Docker.
• Set PUBLIC_URL=/front if needed to ensure assets load correctly.