@mondora/microfrontends/README.md

Library for embedding frontends into one another

# @mondora/microfrontends

Library for embedding frontends into one another.

## Install

```
yarn add @mondora/microfrontends
```

## Use

### In parent apps

```ts
import { ChildApp } from "@mondora/microfrontends";

// Create the iframe for the child app and attach it to the dom
const iframe = document.createElement("iframe");
iframe.src = "https://child.app";
document.body.appendChild(iframe);

// Create the child app
const childApp = new ChildApp({
  iframe: iframe,
  // Methods that the child app will be able to call
  suppliedMethods: {
    echo: input => input
  },
  // Data to pass to the child app at launch
  launchData: {
    authToken: "authToken"
  },
  // Function called when the child app is launched
  onLaunched() {
    console.log("child app launched");
  }
});

// Launch the app
childApp.launch();
```

Or, if you're using React:

```tsx
import { ChildAppReactComponent } from "@mondora/microfrontends";

<ChildAppReactComponent
  url="https://child.app"
  suppliedMethods={{
    echo: input => input
  }}
  launchData={{
    authToken: "authToken"
  }}
  launchingPlaceholder={<span>{"Launching child app..."}</span>}
  onLaunched={() => {
    console.log("child app launched");
  }}
/>;
```

### For child apps

```ts
import { ParentApp } from "@mondora/microfrontends";

// Get a reference to the parent app
const parentApp = new ParentApp({
  onLaunch(launchData) {
    // Start your child app with the launchData supplied by the parent. Example
    // for a React app:
    ReactDOM.render(<App data={launchData} />);
    // When the function returns, the parent app is notified that the child app has launched
  }
});

// Somewhere else in the app, after launch...

// Call the methods supplied by the parent
parentApp.call("echo", "hello").then(result => {
  console.log(result);
});
```

## API

### `ChildApp`

Used from the parent app, creates and launches a child app into an iframe.

Constructor options:

- `iframe` (required): the iframe pointing to the child app
- `onLaunched` (required): function called when the child app is launched
- `childOrigin`: the origin of the child app. In most cases it's detected
  automatically
- `suppliedMethods`: methods that the child app will be able to call
- `launchData`: data to pass to the child app on launch

#### `launch()`

Launch the child app.

##### Returns

Nothing.

### `<ChildAppReactComponent />`

Used from the parent app, React component that creates, launches, and renders a
child app.

Accepted props:

- `url`: see `ChildApp` constructor options
- `onLaunched`: see `ChildApp` constructor options
- `childOrigin`: see `ChildApp` constructor options
- `suppliedMethods`: see `ChildApp` constructor options
- `launchData`: see `ChildApp` constructor options
- `launchingPlaceholder`: placeholder to show while the child app is launching
  (e.g. a spinner)
- `className`: class assigned to the child app iframe

### `ParentApp`

Used from the child app. It attaches to the parent app, receives launch data and
tells the parent when the child has finished launching. It can be used to call
methods supplied by the parent.

Constructor options:

- `onLaunch` (required): function called when the child app is launched
- `parentOrigin`: the expected origin of the parent app. If the parent's origin
  differs from it, the child won't attach to it. When not supplied, the child
  attaches to the parent regardless of origin

#### `call(name, ...params)`

Calls a method supplied by the parent app. Throws an error if the child has not
launched yet.

##### Params

- `name` (required): the name of the method to call
- `...params`: the parameters to pass to the method. They must be
  JSON-serializable, as they are sent through a cross-window channel

##### Returns

A promise to the return value of the parent method.