Portal
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.
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
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)
},
})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.
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
publicfolder
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',
},The shell module is required to setup a number of technical classes and initializes the boot mechanism. The required elements are:
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"),
})
}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()
}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
}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: ...
processor: new ManifestProcessor({
hasFeature: (feature) => true,
hasPermission: (permission) => true
})
});
}The property processor is an optional argument, that can bve provided when manifests are processed on the client side. The
optional hasFeature and hasPermission can be set to pass the corresponding logic.
Different loading strategies are implemented:
-
RemoteDeploymentLoadercreated with an array of{name: <name>, url: <url>}will load the manifests. -
ServiceDeploymentLoaderwill use thePortalServiceto receive a property configuration
If not specified, no additional manifests will be fetched.
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.
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()
);
}
}Every microfrontend needs to
- expose ist
manifest.jsonas a public asset - define a microfrontend module in a
Module.tsfile.
The file name is essential as the remote logic expects to load it exactly under this name!
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?
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>So we already solved the problem how to have distinct instances per component hierarchy, but we also need to solve the problem of reactivity.
We will borrow some of the MobX ideas and integrate that with the existing mechanisms.
Example:
@injectable({scope: "environment"})
@reactive
class Counter extends Controller {
@observable count = 0
@computed
get double() { return this.count * 2 }
@command()
async increment() {
await new Promise(r => setTimeout(r, 1200))
this.count++
}
@command()
async decrement() {
await new Promise(r => setTimeout(r, 1200))
this.count--
}
@command()
reset() { this.count = 0 }
}Any injectable can be marked as reactive which will respect the observable, computed, action similar to MobX.
command is a new concept as it both is an action and creates a stateful command object that is accessible in the base class Controller that offers methods
execute(name: string, ...args: any[]): anyenable(name: string, state = true)isEnabled(name: string): boolean
The enabled status is observable as well!
Let's look at an example:
export const CounterView = () => {
useObserver()
const counter = useLocalEnvironment().get(Counter)
const busy = !counter.isEnabled("increment")
return (
<div>
<div>
{counter.count}
</div>
<div className="cv-double">×2 = {counter.double}</div>
<div>
{busy ? "executing…" : "ready"}
</div>
<!-- + / - -->
<div>
<button
disabled={busy}
onClick={counter.decrement}
>
−
</button>
<button
disabled={busy}
onClick={counter.increment}
>
+
</button>
</div>
</div>
)
}useObserver() will make sure that the renderer will retrigger whenever changes occur!
The enabled status will change automatically while the comamnd is executing!
Now think of how many lines of code would be necessary to implement that low-level!
Additionally, if we already apply AOP mechanisms ( the methods are internally replaced by around methods ) we could add additional logic easily.
Example:
@around(methods().decoratedWith(command as any).thatAreSync())
around(invocation: Invocation): any {
const ctrl = invocation.target as Controller
const name = invocation.method().name
const start = performance.now()
try {
return invocation.proceed()
}
finally {
const duration = performance.now() - start
console.log(`< ${name} finished in ${duration.toFixed(2)} ms`)
ctrl.enable(name)
}
}:-)
A showcase app shows a shell and a microfrontend.
API docs are available here