Integrate Microfrontends into OneCX

The script toggle-mfes.sh integrates (activates) a locally running microfrontend into the OneCX environment, allowing it to interact with other microfrontends. This process is also reversible.

How it works: The script creates a small configuration file in Traefik, tailored to the local microfrontend. Traefik then forwards requests from the Docker network to the external local microfrontend. The script can be run from the root directory of the onecx-local-env repository.

The Traefik configuration files are stored in init-data/traefik/active/. Traefik immediately detects any changes there.

Here is the command to list the currently integrated microfrontends:

./toggle-mfes.sh  -l

Figure 1. List of integrated Microfrontends

Precondition

Before a microfrontend can be successfully integrated into OneCX, it must be started.

Start Angular ng Microfrontend on port 6021

npm run start -- --port 6021 --host 0.0.0.0 --disable-host-check --public-host=http://localhost:6021

Start Angular nx Microfrontend on port 6021

npm run start -- --port=6021 --host 0.0.0.0 --disableHostCheck --publicHost=http://localhost:6021

Checkpoint

Please check the microfrontend is up and running by accessing the public host URL in Browser.

http://localhost:6021/remoteEntry.js

The remoteEntry.js should be loaded - the content is displayed. The ./toggle-mfes.sh script does not check this.

Available Flags

The script accepts several optional flags to customize its behavior. All options may only be used separately!

The flags are:

-a: Enable one or more local microfrontends. In addition to the microfrontend name, you can optionally specify a port and path. The default port is 4200.

If the microfrontend is one of OneCX Core products and no port is specified then predefined ports are used.
-c: Cleanup, remove all existing configurations
-d: Deactivate one or more local Microfrontends
-h: Display this help and exit
-l: List of currently integrated local microfrontends

Examples

Integrate my App with specific path

The local microfrontend my-app runs on http://localhost:4200 (standard Angular).

/my-app-path is the path under which the microfrontend is accessible within OneCX.

./toggle-mfes.sh  -a my-app::/my-app-path

Figure 2. Successful integrated "my-app"

Integrate several Apps

Integrate workspace on standard port 5025 AND user-profile on port 5027. Since no path is specified, the default path is used: /mfe/<name-of-microfrontend>

./toggle-mfes.sh  -a workspace user-profile:5027

Figure 3. Successful integrated Microfrontends

Integrate OneCX Shell

The integration of the shell requires a special path mapping. Hereby the path is not completely stripped. Define the strip path to be used at the end.

./toggle-mfes.sh  -a shell::/onecx-shell/:/

Figure 4. Successful integrated OneCX Shell

Because OneCX Shell is a microfrontend with a special role in OneCX it have to be started with a specific command:

npm run start:local-env

Deintegrate my App

The -d option allows you to undo an integration. The same rule applies to the port: if the port is not 4200, it must be specified.

./toggle-mfes.sh  -d my-app:12345

Figure 5. Successful deintegration

Deintegrate ALL Apps

The Traefik configurations are being cleaned up: All specific configuration files for the Microfrontend integration are being deleted.

./toggle-mfes.sh  -c

Figure 6. Reset all Microfrontend configurations in Traefik

There is no need to deintegrate a microfrontend after use. Simply stopping the local microfrontend is sufficient. Traefik will then automatically route requests to the corresponding microfrontend in Docker Compose.

Routing & Priorities

As described earlier, Traefik is responsible for routing. Each route is assigned a priority, which Traefik derives by default from the length of the rule: the longer the rule, the higher the priority. To avoid routing collisions, the local microfrontends are configured with a significantly higher priority.

This means you can run multiple microfrontends with the same routing rule in parallel and still control which microfrontend is used in OneCX. This is very useful if you want to use locally running microfrontends without having to stop the corresponding service in Docker Compose.

The Traefik configuration generated when integrating a microfrontend (see above) sets a significantly higher priority for this route, so that the local microfrontend is used preferentially.

Example: Prioritize local Microfrontend

In this example, the OneCX Workspace microfrontend is running both in Docker Compose (Service: onecx-workspace-ui) and locally (Service: local_workspace). The local instance is used preferentially because it has a higher priority (323) than the Docker Compose instance (52).

Figure 7. Example routing for OneCX Workspace microservices