front-components - compose different frontend microservices

Compose different microfrontend in a portal.

You can either instantiate a service as uncontrolled: it has access to browser url, and a global event bus provided by this package.

Or you can instantiate a service as controlled by another one: it has access to a scoped router, and a scoped event bus

Install

npm install --save front-components

Registering a service

Service A should register itself as soon as it can, and provide:

• a unique identifier
• a way to mount this service on DOM
• a way to unmount this service

import { registerInstance } from "front-components";

function mount(domElement) {
  // ... For exemple: ReactDOM.render(..., domElement)
}

function unmount(domElement) {
  // ... For exemple: ReactDOM.unmountComponentAtNode(domElement);
}

registerInstance({
  serviceId: "service-A",
  mount,
  unmount,
});

Instantiating a service

Load your service from you portal or another service, using its unique identifier. If service is in a local file you can use require, if it's on remote file you can use <script> tag or even systemJs:

• instantiate an uncontrolled service with: instantiateAt('service-A', domElement);
• instantiate an controlled service with: instantiateAt('service-A', domElement, { isControlled: true });

Events

To emit and listen to events from a service or portal:

import { emit, on } from "front-components";

emit("my-event");
on("my-event", (data) => console.log(data));

Location

A service should not directly access window.location and other history related stuff. Instead, it should gain access to navigation history using a plugin. For example, for React-router, you can use history from our plugin:

import { getReactRouterHistory } from "front-components-history";

const history = getReactRouterHistory();
// uncontrolled service => history will be browser history
// controlled service => history will be memory history

Basic usage

Some exemple with React.

Portal instantiate uncontrolled service

An uncontrolled service emit and listen to events in global bus. Portal has access to global event bus.

// ... service-a/index.js
import { emit } from "front-components";
import { getReactRouterHistory } from "front-components-history";

function mount(domElement) {
  // This will be browser history as service is uncontrolled
  const history = getReactRouterHistory();

  ReactDOM.render(<App history={history} />, domElement);
  emit("hello", { foo: "bar" });
}

function unmount(domElement) {
  ReactDOM.unmountComponentAtNode(domElement);
}

registerInstance({
  serviceId: "service-A",
  mount,
  unmount,
});

// ... portal/index.js
import { instantiateAt, on } from "front-components";

// Listen to global events
on("mounted", (data) => {
  console.log(data); // Once service-a will be mounted, this will be logged
});

// Instantiate service A
const div = document.getElementById("root");
instantiateAt("service-A", div).then(() => {
  console.log("service A instantiated");

  document.location = "new-url"; // will redirect service A
});

Portal instantiate controlled service

An controlled service emit and listen to events in a scoped event bus. Portal has no direct access to this event bus. Portal can retrieve service event bus after service has been mounted.

// ... service-b/index.js
import { emit } from "front-components";

function mount(domElement) {
  // This will be a memory history as service is controlled
  const history = getReactRouterHistory();

  ReactDOM.render(<App history={history} />, domElement);
  emit("hello", { foo: "bar" });
}

function unmount(domElement) {
  ReactDOM.unmountComponentAtNode(domElement);
}

registerInstance({
  serviceId: "service-b",
  mount,
  unmount,
});

// ... portal/index.js
import { instantiateAt, on } from "front-components";

// Listen to global events
on("mounted", (data) => {
  console.log(data); // This will never print, as service b is controlled
});

// Instantiate service B
const div = document.getElementById("root");
instantiateAt("service-B", div).then((controls) => {
  controls.events.on("an-event-from-service-b", (data) => {
    console.log(data); // This will print next time service b emit an event
  });

  // will move service B to a specific location, independant of browser url
  controls.history.push("/service-b-specific-url");
});