Bloomreach Navigation Application

Introduction

This project contains the code for the navigation application, nav-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.

These client apps can then use the @bloomreach/navigation-communication library to communicate with the nav-app API to execute tasks.

Structure

This is an Angular workspace generated by the Angular CLI. The src folder contains the nav-app application.

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.

Development

For a development setup:

pnpm start

Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.

Note: the development setup for the nav-app expects the ./apps/example-iframe-application to be running on http://localhost:4300/. Please follow the instructions in the ./apps/example-iframe-application README to start the example app, or run pnpm start from the root of the project.

Loading Mechanisms

The way the navigation application loads differs between our two products, "Discovery" and "Content". The primary differences lie in how the initial settings are loaded and how the dist folder is organized.

Discovery

For the Discovery product:

• The application is built with pnpm run build:iam or ng build --configuration production-iam.
• The application is deployed in a Docker container.
• The application loads the initial settings from /iam/nav-settings as is defined in ./src/environments/environment.iam.ts.
• The dist folder is organized such that the index.html file is located directly under dist/ and all other files are located under dist/navapp-bundle.
  • This simplifies the routing/proxying configuration in the virtual service that serves the application.
  • /navapp/ should load the index.html file.
  • /navapp/navapp-bundle/ should load the rest of the files.
  • /navapp/foo/bar should load the index.html file again.
• The index.html file contains a <base> element that sets the base URL to /navapp/navapp-bundle/.
  • This ensures that all relative URLs are resolved correctly, irrespective of the current URL.

Content

For the Content product:

• The application is built with pnpm run build or ng build --configuration production.
• The application is deployed on NPM and served via Wicket.
• The application loads the initial settings from ../../ws/navigation-settings as is defined in ./src/environments/environment.content.ts.
  • The path is relative to the location of the application on the server; the navapp is served from <application-root>/angular/navapp
• The dist folder is organized in a simpler structure, with all necessary files located directly under dist.

These differences ensure that each product can be tailored to its specific deployment and operational requirements.

Custom Log Level

To define a custom log-level using the local-storage API of the browser, follow these steps:

1. Open the browser's developer tools (usually by pressing F12 or Ctrl+Shift+I).
2. Navigate to the "Console" tab.
3. Set the desired log level by executing the following command in the console:

   localStorage.setItem('br_nav_log_level', 'DEBUG');

4. Refresh the page to apply the new log level.

The available log levels are defined in the ngx-logger library, which is used by the nav-app. The available log levels are: TRACE, DEBUG, INFO, LOG, WARN, ERROR, FATAL, and OFF.

To reset the log level to the default value, execute the following command in the console:

localStorage.removeItem('br_nav_log_level');

Build

To produce a production build:

pnpm build

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

Running unit tests

To run the unit tests:

pnpm test

Linting

To run the linter:

pnpm lint

This will lint both the TypeScript and the SCSS files.

Documentation

To generate the documentation:

pnpm docs

Runtime Configuration

Domain-specific values (cookie domains, tools hostnames, development domains, domain mappings, external links) are loaded at runtime from runtime-config.js, which is referenced in index.html before Angular bootstraps.

The configuration structure is defined by the RuntimeConfig interface in src/app/models/runtime-config.interface.ts.

There are two sources for this file depending on the deployment target:

| Deployment | Source | Loaded at | |---|---|---| | Discovery / Garuda (Docker/Helm) | Kubernetes ConfigMap generated from devops/charts/values.yaml | Deploy time | | Content (NPM package) | Bundled from src/config/prod/runtime-config.js | Build time |

WARNING: src/config/prod/runtime-config.js and the domainConfig section in devops/charts/values.yaml must be kept in sync. When adding or modifying domain configuration, update both files to avoid environment mismatches.

Deployments

The @bloomreach/navigation-application package is released on multiple channels:

• A Docker container is built and pushed to the discovery.prod.br-engops.io/discovery-images repository.
• This container is built specifically for the Discovery environment.
• Alongside the container, a Helm chart is published to the https://maven.bloomreach.com/repository/discovery-charts repository.
• An NPM package is published to the @bloomreach/navigation-application package on NPM.
• This package is built specifically for the Content environment.
• A copy of the dist folder is deployed on S3, one for every realm.
• This is done for the legacy IAM-based deployments.

Publishing a Pre-release NPM Package (for testing)

The automated release pipeline only publishes from main. To test changes in the Content environment before merging, you can manually publish a pre-release version:

cd apps/navigation-application

# 1. Log in to npm (required if your token is expired or revoked)
npm login --scope=@bloomreach

# 2. Build the production configuration (includes runtime-config.js)
pnpm build

# 3. Set a pre-release version (do NOT commit this change)
npm version 2.15.1-MERCH-XXXX.0 --no-git-tag-version

# 4. Publish with a "dev" dist-tag so it does not affect "latest"
npm publish --tag dev --access public

# 5. Revert the version change
git checkout package.json

Then in the Content repo, install the pre-release version:

npm install @bloomreach/navigation-application@dev
# or pin to the exact version:
npm install @bloomreach/[email protected]

Note: The --tag dev flag is critical -- it prevents the pre-release from becoming the default latest version that other consumers would pick up.