Akinon App Shell Library

The app-shell library is designed to orchestrate the integration of micro-frontend applications, providing a unified shell for navigation, theming, and inter-app communication.

Installation

To incorporate the app-shell library into your main application, execute:

pnpm install @akinon/app-shell

Usage

Incorporate the AppShellProvider at the top level of your main application:

import React from 'react';
import ReactDOM from 'react-dom';
import { AppShellProvider } from '@akinon/app-shell';
import MainApp from './MainApp';

ReactDOM.render(
  <AppShellProvider apps={yourAppsConfig} navigation={yourNavigationHandler}>
    <MainApp />
  </AppShellProvider>,
  document.getElementById('main')
);

yourAppsConfig should be an array of app configurations, including IDs, URLs, and types.

API

AppShellProvider

Props:

• apps: An array of application configurations.
• navigation: Navigation handler for the shell.
• data: Optional shared data for micro-frontends. The shell adds shellBaseUrl to the copy each app receives; see resolveUrl below.

navigation

interface ShellNavigation {
  navigate: (payload: ShellNavigationPayload) => void;
  resolveUrl?: (payload: ShellNavigationPayload) => string | undefined;
}

• navigate receives { id, path, external, newTab }. When newTab is true the host opens the new browser tab itself: the shell forwards the flag and never calls window.open, because only the host knows its own url grammar. Build the destination with the same helper the same-tab branch uses, so the two cannot drift apart. An external path arrives from the iframe untouched, so open it only when it is an http: or https: url: a javascript: or data: url handed to window.open runs in the shell's context, and the shell does not filter it.
• Neither callback is captured when an app's iframe is set up: the shell reads both off the navigation object of your latest render, so a handler rebuilt around render-scoped values (the active language, the active channel) is the one that runs on the next call.
• resolveUrl is optional. It answers "what url would you navigate to for this payload" without navigating, and the shell broadcasts the answer to the app as data.shellBaseUrl; clients join their own paths onto it to render real <a href target="_blank"> links. The shell calls it on every SET_DATA emit — once per app when its iframe hands over its config, once per rich-modal iframe, and again for every app whenever the shell's data prop changes — always with an empty path, so the returned url carries the host url grammar only. The id it receives is the id of the app that owns the bus; a rich modal is resolved with its parent app's id, because its own uuid is not an app the host has registered.
• resolveUrl should return an absolute url. The shell drops any query string and hash from it before it is broadcast — the client appends the app path to it as plain text, so either would swallow the path. A relative url is resolved against the shell's own origin. Returning undefined or an empty string, throwing, or not implementing resolveUrl at all leaves shellBaseUrl out of the data the app receives: the shell never substitutes the page origin, since a url built from the wrong origin is exactly the failure this callback exists to prevent.

Configuration

Define each micro-frontend application with:

• id: Unique identifier.
• url: Source URL for the iframe.
• type: Type of app, e.g., 'full_page' or 'plugin'.

Extending

The app shell is designed to be extendable. Implement custom logic for navigation, theming, and more to fit the needs of your micro-frontend architecture.

For detailed documentation on extending the app shell, configuration options, and more advanced use cases, refer to the full documentation.