How to: Integrate your existing application with the Console UI

The Console UI micro-frontend acts as the glue that binds the application and the end-user together. After you register your App in the OS1 developer portal and integrate it with the Console UI micro-frontend, it is then ready to be made available to end-users on their respective landing pages.

For more information about Console UI, see Console UI Overview.

This how-to outlines the steps to integrate your App with Console UI.

1. Set up your webpack configuration.

The integration uses webpack to connect your App to the Console UI. Depending on the folder structure, you will need to make the modifications below to all of your webpack configuration files(ex. webpack.config.js, webpack.prod.js, and similarly for other environments).

plugins: [
    remotes: {
      header: "[email protected]://console.os1.delhivery.com/header/remoteEntry.js",
    },
]

🚧

Multiple webpack configurations

There are cases where your project might contain multiple webpack configuration files (such as wepback.prod.js etc.). Be sure to apply the above changes to all the config files.

You can now import the Console features anywhere in your application.

📘

Note

If you are using Craco config, you might have to make changes to your modulefederation.config.js file instead of the webpack.config.js

2. Initialize the Header within your application

Next, add the header to your App. To determine whether the integration is successful :

  • Unauthorized users opening your App are redirected to the login page.
  • Authorized users who are able to access the application see a header component on the top of the application.
    To add the header to your App, import the initialize function and call it as follows:
  • Note that initializing must be done as pure javascript. i.e. If you're using react, initialize outside of your app.
import { initialize } from "header/initialize";

initialize();

Initialization is an asynchronous method. You will have to subscribe to the shared access bundle to ensure the header initialization is complete

Here's an example with a React Provider:

import { sharedAccessBundle } from 'header/AuthenticatedHeader';
import { PropsWithChildren, useEffect, useState } from 'react';

const ConsoleUIProvider = ({ children }: PropsWithChildren) => {
  const [isFetched, setIsFetched] = useState(false);

  useEffect(() => {
    sharedAccessBundle.subscribe((parameters: any) => {
      if (parameters?.tenantId && parameters?.accessToken) {
        setIsFetched(true);
      }
    });
  }, [isFetched]);

  if (isFetched) {
    return <>{children}</>;
  } else {
    return <></>;
  }
};

export default ConsoleUIProvider;

Then add the provider to root:

import initialize from 'header/initialize';
import ConsoleUIProvider from './ConsoleUIProvider';

initialize();

const root = ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement
);
root.render(
  <ConsoleUIProvider>
    <App />
  </ConsoleUIProvider>
);

3. Make requests with our HTTP client

After header initialization has been completed, all of the console features are available. You can now use our exposed axios client to make requests with predefined http headers already installed. These http headers are required for calling CoreOS APIs.

import { axiosInstance } from 'header/httpClient';

const request: AxiosRequestConfig = {
  url: `${YourConfigBaseUrl}/therestofyourrequesturl+params`,
  method: 'get | post | delete | put',
  data: { ...yourBodyData },
  headers: { ...extraHeadersIfNeeded },
};
const response = await axiosInstance(request);

Local Development by proxying into your tenant

In order to be able to use your local desktop to develop and test, you must configure a proxy in your hosts file.

Configure proxy

You will need to configure your /etc/hosts file to serve traffic as a domain name for the authentication to work.

First, look up your tenant url in the Developer Portal. For example, if it's https://dlvindia.preprod.dlv2.fxtrt.io, then your TENANT_URL will be preprod.dlv2.fxtrt.io. and your TENANT_NAME will be dlvindia.

TENANT_NAME=<Add your tenant name here>
TENANT_URL=<Add your tenant url here>

# Most Linux distros
echo "127.0.0.1 ${TENANT_NAME}-cdev.${TENANT_URL}" >> /etc/hosts

# Macs
echo "127.0.0.1 ${TENANT_NAME}-cdev.${TENANT_URL}" | sudo tee -a /etc/hosts

📘

Sample App that uses Console

Checkout our sample app repo to see more code samples
https://github.com/OS1-logistics/vehicle-reference-app/tree/main/client