Bloomreach Navigation Communication Library

This library provides a set of utilities to communicate with the nav-app API from a client app. The nav-app is the container application of micro-frontends in BRX. Through configuration it allows the loading of isolated apps inside iframes hosted on any domain.

It uses the postMessage API to communicate with the nav-app via the Penpal library.

Installation

To install the dependencies, run:

pnpm i

Note: this will install all dependencies of the project, i.e. for every package in the monorepo.

Usage

To use this library in your project, install it with:

npm install @bloomreach/navigation-communication

To connect to the nav-app, the client app must load the navigation communication library and register itself with the nav-app following the API.

Example code from a child perspective:

import { connectToParent } from '@bloomreach/navigation-communication';

connectToParent({
  parentOrigin: '<add the origin to allowlist to match the authenticated origin>',
  methods: {
    navigate(path) {
      routeToPath(path);
    },
    beforeNavigate() {
      return outstandingWorkToBeDone();
    }
  }
})
.then((navApp) => {
   // Call a nav-app's method
   navApp.updateNavLocation(location);

   // Access nav-app properties
   const username = navApp.user.name;
 });

Once the application has retrieved the navApp object, it can use that to communicate with nav-app.

Error handling

The communication library can transfer errors from client applications to the nav-app. To facilitate that onError method has been added to the parent API. So if a client application detects any of these errors:

1. session timeout / not properly authenticated / not authorized;
2. unable to handle the path provided via navigate method;

it calls onError method and provides error code and optional error message which can be ignored by the nav-app.

Handling rejected promises when calling a provided parent or child api method is assumed to be done by the implementer of the method. The rejected promise usually tells that something went wrong with the connection. That could be the responsibility of the communication library like handling a timeout and retry of a call.

User session management

Currently there is a method both in the parent and child api onUserActivity. Assuming all iframe apps have some way to detect user activity to prevent active logout this can be used to listen to and communicate to other apps the activity of the user.

When an application detects activity it should communicate this to the navapp which in turn will communicate it to the other apps to prevent them from logging out due to inactivity.

Development

Building

To produce a production build:

pnpm build

The build artifacts will be stored in the dist/ directory.

Developing

To build and watch for changes:

pnpm start

The library will be built and watched for changes. The build artifacts will be stored in the dist/ directory.

Testing

To run the unit tests:

pnpm test

Linting

To run the linter:

pnpm lint

API Documentation

The API documentation can be generated by running:

pnpm docs

The documentation will be generated in the docs folder.