React utilities for PAE
npm install @bluealba/pae-ui-react-core
Core PAE library for PAE microfrontend applications.
It exposes PAE functionality in the form of react elements such as hooks, components, etc. which provide cross-cutting
concerns such as Authentication (Impersonation), Authorization, Service Interaction, Monitoring, etc.
A PAE microfrontend must be created by calling the initiliazeMicroFrontend() function (not although you could directly create a SingleSPA application
that will tied you to SPA and you won't be able to use all the functionality of this PAE library).
``jsx
import React from "react";
import ReactDOMClient from "react-dom/client";
import { initializeMicroFrontend } from "@bluealba/pae-ui-react-core";
import Root from "./root.component";
export const { bootstrap, mount, unmount } = initializeMicroFrontend({
React,
ReactDOMClient,
rootComponent: Root,
errorBoundary(err) {
console.error(err);
return (
{err.message}
The most important part here is that you specify your
of your app and a way to handle errors locally.Utility Functions
$3
Use this function to navigate to a different url. This function is a wrapper around the
single-spa navigateToURL function`typescript jsx
import { navigateTo } from '@bluealba/pae-ui-react-core';navigateTo('/path/to/another/module');
`Hooks
PAE provides the following hooks to access data and interact with PAE services.
$3
Retrieve the current user information as well as a method to check authorization access.
jsx
import { useAuth } from '@bluealba/pae-ui-react-core';const TestComponent = () => {
const { authUser, hasAccess } = useAuth();
return (
{authUser.displayName}
{/ e.g: John Doe /}
{authUser.username}
{/ e.g: johndoe /}
{authUser.familyName}
{/ e.g: Doe /}
{authUser.givenName}
{/ e.g: John /}
{authUser.initials}
{/ e.g: JD /}
{hasAccess('operation1', 'operation2')}
);
};
`$3
Use this hook to get access to the current ecosystem applications and modules catalog
jsx
import { useCatalog } from '@bluealba/pae-ui-react-core';const TestComponent = () => {
const { catalog } = useCatalog();
return (
{catalog.map((item) => (
{item.name}
{item.version}
))}
);
};
`$3
Use this service to make a request to a PAE microservice. This way you don't need to know under which path it is exposed
by the system (gateway). And you just need to know the service/module full name.
It returns a function that is fully compatible with the
function`typescript jsx
const invoker = useServiceInvoker("@acme/my-wheather-service");return (
)
`Internally this hook uses the catalog to resolve the service full URL (there is also a
hook)$3
Use this service to track Application Usage Events. This is the frontend API to PAE Habits Service.
`typescript jsx
const trackEvent = useTrackEvent();const trackClickEvent = useCallback(async e => {
await trackEvent("button-click-app2", {
buttonText: e.target.innerText
});
},
[trackEvent]
);
return (
)
`The
function receives the name of the event and a custom payload that can be anything you want.
PAE will automatically store this event with contextual information such as: the current User, the Module that triggered
this event and its version and the associated Application (if the module has one), together with timestamps.Alternatively you can also use
useTrackEvents() (plural) hook to publish more than one event in a single call.Authorization
In order to render a piece of JSX conditionally based on authorization there are two ways to do this.
* using the
useAuth() hook: which is more "manual" but powerful
* using the component$3
With this hook you get the current user and a utility function
hasAccess()typescript jsx
const MyComponent = () => {
const { authUser, hasAccess } = useAuth();
return (
{hasAccess('operation1', 'operation2') && (
access granted
)}
)
}
`$3
This component only renders the children content if the user has the specified operations
typescript jsx
const MyComponent = () => {
return (
You have access to this section
)
}
`
If it has no access then nothing is rendered.There's also an optional property
with which you can specify the content to be displayed in case the user has no grant on the operations.This prop is overloaded and you can pass different content.
* The name of a React component
* A render function
* A straight JSX content
For example a render function
`typescript jsx
// passing a React component
You have access to this section
// passing a render prop function
You have access to this section
// passing content directly
Section not allowed
You have access to this section
Extension Points
They allow UI modules to declare points such as React components that can be later replaced by another value/component
from another UI module dynamically.
$3
There are two ways for a MF to declare an extension point that can be later extended by other MFs. Internally they both the the same thing, it is just a matter of a different flavor of API. *
component: useful to declare an extension point inline within a JSX
* extensionPoint() HOC (high-order component): useful to make a whole component replaceable as an extension point.#### Declaring an extension point inline with ExtensionPoint component
In any component’s JSX you can declare an extension point, like a “slot” to be extended by other MFs.
`typescript jsx
const MyComponent = () => {
return (
Hello
)
}
`This will create an extension point that is scoped to the current module with the given name. For example
You can include children elements that will be the fallback/default content in case nobody extends this extension point
typescript jsx
const MyComponent = () => {
return (
Hello World
)
}
`#### Declaring a component as an extension point with the HOC
There’s another common case where you want a whole component to be “replaceable” completely as an extension point. In this case you can use the
HOC as a shortcut to void creating a wrapper component just for this.For example the
pae-shell-ui (or any MF) declares a React component to be an “extension point” by simply using a new pae-ui-react-core HOC wrapping the component that is the menu`typescript jsx
const MenuApplicationSelector: React.FC = () => {
// regular react component
}// the displayName becomes the extension point name by inference (it can be set manual optionally in the hoc call)
MenuApplicationSelector.displayName = 'ApplicationSelector';
// here we are wrapping the component using the HOC which makes it an extension point
export default extensionPoint(MenuApplicationSelector);
`If no-one is extending the point the the component will be rendered. If someone extends it then this component won’t be mounted at all, and it will be replaced by the extending component.
$3
Then another MF can extend that point in two different ways:
*
: Using a built-in component rendering the content inline
* useExtendExtensionPoint: using a hook which allows more programmatic controlWe will see both options below:
#### Using the ExtendExtensionPoint component
With a React Component provided by pae-ui-react-core
`typescript jsx
// somewhere in your MF DOM
Hello World From an Extension!
`#### Using the useExtendExtensionPoint hook
Or more "manually" using the useExtendExtensionPoint hook
typescript jsx
const Root = () => {
// register the extension
useExtendExtensionPoint('@bluealba/pae-shell-ui', 'ApplicationSelector', CustomApplicationMenu)
return your app content here
}
`In both cases the extension follows the regular React lifecycle ! Meaning that when the component that called the hook/included the extension component gets unmounted, then the extension point gets un-registered dynamically.
Then this means that components are extended / disengaged dynamically.
Library Development
This section is for PAE platform developers or anyone that wants to make changes to this repository.
This Library is one of the "client facing" API for PAE. Meaning that it is the API that exposes all PAE behavior to
microfrontends for different customers and projects.
Because of this we must be very careful with changes in terms of backward compatibility. This is the first layer of
integration. Some projects might be using different versions of PAE and this library.
Therefore we should try to reduce the number of non-backwards compatible changes !!
Development Process and Releasing
To make modifications and have them automatically picked while working locally you should run
bash
npm run build-and-publish:watch
`
Just make sure that you have the cloned as a sibling folder to this repo.The following content describes what happens under the hood.
The cycle goes like this:
* Create feature branches to work in a feature
* Eventually merge them into
develop branch. This will build but not publish any package
* Once you reached a point where you want to publish a new release. Bump the version to the target version you want to publish and create a PR to main
* Once merged into main the pipeline will automatically build and publish the version to NPMjs public repository.Now there are 2 more steps to follow in order to start using this published version (next sections)
$3
In the PAE architecture the orchestrator is the one that automatically includes this library in runtime for all
applications. It has its own locally cached bundle js of this library.
To update it you must
* Edit the
file in pae-orchestrator-service to update the "shared-libraries" entry with the version you just published
* Run npm run build:libs in the orchestrator so that it fetches this new version and caches it
* Merge to develop to create a new build/image of the orchestrator
* Apply it to any environment / product you want$3
Every microfrontend includes this library as a
devDependency` so that Typescript can use it for type checking.So once you release a new version of this lib and update the orchestrator to use it. When you bump the orchestrator
version for a particular product, you should be going through all your microfrontends and update the devDependency
to match the released version.