Portal

Introduction

Portal implements a react portal framework supporting microfrontends vastly simplifying implementation efforts since a number of technical challenges every application has to solve are already part of the framework.

• integration of a DI solution
• centralized error handling ( including error boundaries )
• session handling
• optional i18n solution
• meta-data based approach that allows for
  • filtering of available features according to authentication, authorization or other aspects ( e.g. feature flags )
  • automatic router configuration according to the metadata
  • dynamic navigation features that are based on the meta-data and custom rules
  • feature outlets that cover both local and federated components and allow for custom async preloading logic ( e.g. i18n loading )
• custom application configurations with support for both client and server side logic

While the framework supports enterprise portals with dynamic microfrontends - and server side configuration mechanisms - as one extreme it also covers small local only applications without significant coding and rampup overhead, making it a one-size-fits-all framework.

Basic Solution Idea

The main idea for most of the mechanisms is that modules expose meta-data of "what is inside", by annotating available "features" ( named components used internally or part of the routing ) with special decorators.

@Feature({
  id: 'public-navigation',
  label: 'Navigation',
  visibility: ["public"], // visible without a session
  features: [],
  permissions: []
  tags: ['portal'], // needed to identify this special feature
  path: '/'
})
export class PublicNavigationFeature extends React.Component {
    ...
}

A parser - as part of the build - will locate those features and generate a manifest.json which can be processed by different mechanisms.

{
  "id": "shell",
  "label": "Shell",
  "version": "1.0.0",
  "moduleName": "ApplicationModule",
  "sourceFile": "apps/shell/src/main.tsx",
  "description": "Shell",
  "features": [
     {
      "id": "public-navigation",
      "label": "Navigation",
      "path": "",
      "visibility": [
        "public"
      ],
      "tags": [
        "portal"
      ],
      "features": [
      ],
      "permissions": [
      ],
      "component": "PublicNavigationFeature",
      "sourceFile": "apps/app/src/navigation/PublicNavigation.tsx",
    },
    ...
  ],
  ...
}

If we think of a setup including a shell and federated microfrontends, those manifests are the basis for an application configuration by merging different manifests according to custom rules and setups and booting the application with a tailored configuration. Possible rules - that are typically executed on the server side - are rules regarding

• static configurations ( enabling/disabling microfrontends or features per admin ui )
• roles and permissions
• feature flags
• client characteristics ( e.g. screen resolution )

As already stated, an enterprise portal will have the corresponding data management, services and respective administrative interfaces to compute custom configurations on the server side. As the framework should also cover small apps, a standalone purely client driven approach is also possible. So different scenarios are possible:

Standalone application

Microfrontend application reading remote manifests on the client side

Microfrontend application with a server side configuration

Lets' look at the details

Feature Declaration

In order to extract the meta data, react components need to be decorated with the decorator Feature that accepts the config values

interface FeatureOptions {
  id: string;
  icon?: string;
  permissions?: string[];
  description?: string;
  tags?: string[];
  features?: string[];
  visibility?: ('public' | 'private')[];
  i18n?: string;
  label?: string;
  path?: string;
  parent?: string;
  clients?: ClientConstraints;
}

There are use-cases where the same application needs to adapt to to different client characteristics, starting with the screen resolution. While there are some media query related mechanisms that could be used, there are of course limits and often lead to unmaintainable and scattered code. The approach taken here is completely flexible by defining different features that match certain aspects and that are picked dynamically during the runtime.

The field clients defines constraints that must be fulfilled and include

• Screen size (xs–xl)
• Orientation (portrait / landscape)
• Platform (ios, android, web, macos, etc.)
• Capabilities (touch, multitouch, stylus)
• Device type (phone, tablet, desktop)

Example:

@Feature({
    id: "navigation",
    label: "iOS IPad Navigation",
    path: "",
    tags: [],
    permissions: [],
    features: [],
    visibility: ["public"],
    clients: {
        platforms: ["ios"], // Native mobile platforms
        screenSizes: ["sm", "md", "lg", "xl"],  // All except xs (phones portrait)
    },
})

Module Declaration

Every project adds top-level meta-data by including a module class inheriting from AbstractModule and decorated with @Module given the options:

@Module({
  id: "microfrontend",
  label: "microfrontend module",
  version: "1.0.0",
  description: "Micro Frontend Module",
})
export class MicrofrontendModule extends AbstractModule {
    // override

    async setup(): Promise<void> {
      await super.setup()

      ...
    }
}

This class is also the basis for the corresponding DI container and may include any @create functions.

Feature Extraction

A builtin tool is used to extract the data by adding the corresponding target in the corresponding project.json

"targets": {
    "scan-metadata": {
      "executor": "nx:run-commands",
      "options": {
        "command": "nx run metadata:scan --moduleFolder=apps/app --outFile=apps/app/src/manifest.json"
      }
    }
}

Depending on the type of project the manifest.json will be placed differently:

• the shell will place it under src
• microfrontends need it as an asset, so typically under the public folder

The tool not only generate a manifest.json but will also update the exposes section of the webpack.config.js to reflect the exposed components.

Example:

  exposes: {
        "./MicrofrontendFeature": "./apps/microfrontend/src/feature",
        './Module': './apps/microfrontend/src/Module',
      },

Shell Module

The shell module is required to setup a number of technical classes and initializes the boot mechanism. The required elements are:

Locale Manager

The locale manager defines the current locale and the number of supported locales:

Example:

@create()
createLocaleManager() : LocaleManager {
    return new LocaleManager({
      locale: "de-DE",
      supportedLocales: ["de-DE", "en-US"],
      backingStore: new LocalStorageLocaleBackingStore("language"),
    })
}

Translator

The Translator is responsible to load i18n values:

Example:

@create()
createTranslator(localeManager: LocaleManager) : Translator {
     return new TranslatorBuilder()
      .loader(new AssetTranslationLoader({ path: '/i18n/' }))
      .localeManager(localeManager)
      .build()
}

Session Manager

The session manager is responsible for the corresponding authentication mechanism and the organization of a session object

Example:

 @create()
  createSessionManager() : SessionManager<any,any> {
    return new SessionManager(new NoAuthenticationService()); // just a dummy
  }

Deployment Manager

The deployment manager is responsible to load a tailored ( merged ) configuration for the current session.

Example:

 @create()
  createDeploymentManager(featureRegistry: FeatureRegistry) : DeploymentManager {
      return new DeploymentManager({
        featureRegistry: featureRegistry,
        localManifest: manifest as Manifest
        loader: ...
      });
  }

Different loading strategies are implemented:

• RemoteDeploymentLoader created with an array of {name: <name>, url: <url>} will load the manifests.
• ServiceDeploymentLoader will use the PortalService to receive a property configuration

If not specified, no additional manifests will be fetched.

Boot logic

The boot logic is embedded in the @onRunning lifecycle method

 @onRunning()
  async onRunning(featureRegistry: FeatureRegistry, deploymentManager: DeploymentManager, sessionManager: SessionManager<any,any>, routerManager: RouterManager) {
     // load deployment

      await deploymentManager.loadDeployment({
          application: "portal",
          client: deploymentManager.clientInfo(), // pass the current client infor in order to filter features
      });

      // let the routing manager create dynamic routes given a "root" page!

      routerManager.setRoot(() => (featureRegistry.finder()
        .withTag('portal')
        .matchesSession(sessionManager.hasSession())
        .findOne()
      ))
  }

After computing an overall configuration given a set of manifests, it will setup the react routes, given a specific root page. In this case a feature with tag portal is used that has a visibility value matching the current session state. Without a session, he is looking for visibility including "public", with a session "private" giving us the chance to have different layouts depending on the state.

All other registered features with a defined path ( which are not lazy child features ) will be added automatically.

Application setup

Booting an application requires several steps:

Environment Creation

The DI environment has to be started given the root module.

Example: Make sure to import all files that include @injectable classes!

export const createEnvironment = async () : Promise<Environment> => {
    const environment = new Environment({module: ApplicationModule})

    await environment.start()

    return environment
}

React root

const environment = await createEnvironment();

const root = createRoot(document.getElementById('root')!);
root.render(
    <EnvironmentContext.Provider value={environment}>
      <App />
    </EnvironmentContext.Provider>
    );

The context is required so that components can access the environment.

A corresponding Application

The essential part is to give the router the chance to render

*Example:

export class App extends React.Component {
    routerManager!: RouterManager;

    static contextType = EnvironmentContext

    declare context: Environment

    async componentDidMount() { 
        this.routerManager = this.context.get(RouterManager);
    }

    override render() {
        return (
            this.routerManager.renderRouter()
        );
    }
}

Microfrontend Module

Every microfrontend needs to

• expose ist manifest.json as a public asset
• define a microfrontend module in a Module.ts file.

The file name is essential as the remote logic expects to load it exactly under this name!

Navigation

The top-level page which will serve as the root of the router typically contains a header, footer and some ways how to navigate, typically with some kind of menu structure.

The interesting part is that, since we already have a dynamic routing setup, the navigation entries should also be dynamic, which is easy doable by simply introspecting the existing features and simply adding <Link>s to s subset of them.

In the provided showcase shell the logic is to iterate over all features found with:

const features = featureRegistry
    .finder()
    .withPath()
    .withoutParent()
    .withVisibility(sessionManager.hasSession()) // only show features that should be visible!
    .withTag('menu') // !
    .find();

Isn't that awesome?

Accessing Environment

As showed a context is already inserted that gives us the chance to access it. Two hooks are implemented:

useEnvironment()

will retrieve the current environment.

Example:

const environment = useEnvironment()
const service = environment.get(SomeService)

useLocalEnvironment()

is a flavor that sets up a child environment ( in the current context ). This child environment will inherit all providers of the parent ( and will reuse existing singleton instances ) but will recreate all instances with scope environment. This respective component - and all of its children - will this have isolated values!

If child components need to access the environment as well, make sure the establish the corresponding context!

Example:

const environment = useLocalEnvironment()

<EnvironmentContext.Provider value={environment}>
   ...
</EnvironmentContext.Provider>

Reactive Classes

So we already solved the problem how to have distinct instances per component hierarchy, but we alos need to solve the problem of reactivity.

Showcase

A showcase app shows a shell and a microfrontend.

API Docs

API docs are available here