Components

AppShell provides three key components for rendering micro-frontend applications:

• AppRenderer - Renders fullpage applications

• PluginRenderer - Renders plugin applications in designated placeholders

• ModalRenderer - Renders applications in modal dialogs

AppRenderer

Renders fullpage micro-frontends managed by the AppShell. It dynamically inserts the application's iframe into the DOM based on the provided application ID.

Usage

import { AppRenderer } from '@akinon/app-shell';

const FullPageAppContainer = () => {
  return (
    <div className="fullpage-container">
      <AppRenderer id={1} />
    </div>
  );
};

Props

Prop	Type	Required	Description
id	number	Yes	Unique identifier for the application iframe, application PK may be used
path	string	No	Path to append to the iframe src URL

With Custom Path

// Renders the app at its web_url + /dashboard
<AppRenderer id={1} path="/dashboard" />

How It Works

1. Retrieve Iframe - Accesses AppShell context to get the iframe reference for the given ID

2. Insert Iframe - Dynamically inserts the iframe into the container

3. Style Adjustment - Ensures iframe occupies full container space

PluginRenderer

Renders plugin-type micro-frontends in specific placeholders. Plugins are designed to be embedded within parts of the application without taking over the entire page.

Usage

import { PluginRenderer } from '@akinon/app-shell';

const Dashboard = () => {
  return (
    <div className="dashboard">
      <main className="content">
        {/* Main dashboard content */}
      </main>
      
      <aside className="sidebar">
        <PluginRenderer placeholderId="dashboard-sidebar" />
      </aside>
    </div>
  );
};

Props

Prop	Type	Required	Description
placeholderId	string	Yes	ID of the placeholder where the plugin should render
params	ApplicationParams	No	Additional parameters to pass to the plugin

ApplicationParams Type

interface ApplicationParams {
  [key: string]: string | number | boolean | string[] | number[];
}

With Parameters

<PluginRenderer 
  placeholderId="product-analytics" 
  params={{
    productId: 'prod-123',
    showChart: true,
    metrics: ['views', 'sales', 'revenue']
  }}
/>

How It Works

1. Identify Plugin - Uses placeholderId to find the matching plugin from AppShell context

2. Match Configuration - Finds the app whose config.placeholder matches the placeholderId

3. Embed Iframe - Inserts the iframe into the placeholder container

Placeholder Configuration

When registering apps, plugins must specify their placeholder:

const registeredApps: RegisteredApp[] = [
  {
    pk: 2,
    name: 'Analytics Widget',
    config: {
      web_url: 'https://analytics.example.com',
      visible_type: 'plugin',
      placeholder: 'dashboard-sidebar' // Matches placeholderId
    },
    is_visible: true,
    is_active: true
  }
];

ModalRenderer

Renders fullpage application content within a modal dialog. Used for rich modals that need to display micro-frontend content.

The uuid is automatically generated by the shell when a client calls showRichModal action. The shell creates the uuid via crypto.randomUUID() and passes it along with path, context, size, and closeIconColor to your modal implementation.

How It Works

1. Client triggers modal - Client calls actions.showRichModal(path, context, size, closeIconColor)

2. Shell generates UUID - Shell creates a unique identifier with crypto.randomUUID()

3. Shell calls your handler - Your showRichModal function receives (uuid, path, context, size, closeIconColor)

4. Render ModalRenderer - Use the received uuid and path in ModalRenderer

Usage

import { ModalRenderer } from '@akinon/app-shell';

// In your shell's actions configuration
const actions: ApplicationActions = {
  showRichModal: (uuid, path, context, size, closeIconColor) => {
    // Shell has already generated uuid, you receive it here
    setModalConfig({ uuid, path, context, size, closeIconColor });
  }
};

// In your modal component
const RichModal = ({ config, onClose }) => {
  return (
    <Modal open onClose={onClose}>
      <ModalRenderer 
        uuid={config.uuid}
        path={config.path}
        size={config.size}
      />
    </Modal>
  );
};

Props

Prop	Type	Required	Description
uuid	UUID	Yes	Unique identifier generated by shell and passed to your showRichModal handler
path	string	Yes	Path to render content within the modal (relative to client's web_url)
size	ApplicationModalSize	No	Size configuration for the modal (defaults to 540x360px)

The context parameter is sent to the client via SET_MODAL_CONTEXT event and accessible through useAppClient().modalContext. The closeIconColor is for styling the shell's modal close button.

ApplicationModalSize Type

type ApplicationModalSize = {
  maxWidth?: number | string;
  maxHeight?: number | string;
};

With Size Configuration

<ModalRenderer 
  uuid="modal-uuid-123"
  path="/order/confirmation"
  size={{
    maxWidth: 800,
    maxHeight: '90vh'
  }}
/>

Complete Example

Here's how all three components work together in a shell application:

import { 
  AppShellProvider, 
  AppRenderer, 
  PluginRenderer, 
  ModalRenderer 
} from '@akinon/app-shell';

const ShellApp = () => {
  const [activeAppId, setActiveAppId] = useState<number | null>(null);
  const [modalConfig, setModalConfig] = useState<ModalConfig | null>(null);

  return (
    <AppShellProvider
      apps={registeredApps}
      navigation={navigation}
      data={sharedData}
      actions={actions}
    >
      <div className="shell-layout">
        {/* Header with plugin slot */}
        <header>
          <Logo />
          <PluginRenderer placeholderId="header-actions" />
        </header>

        {/* Main content area */}
        <main>
          {activeAppId && <AppRenderer id={activeAppId} />}
        </main>

        {/* Sidebar with plugin slot */}
        <aside>
          <PluginRenderer placeholderId="sidebar-widget" />
        </aside>

        {/* Modal for rich content */}
        {modalConfig && (
          <Modal open onClose={() => setModalConfig(null)}>
            <ModalRenderer 
              uuid={modalConfig.uuid}
              path={modalConfig.path}
              size={modalConfig.size}
            />
          </Modal>
        )}
      </div>
    </AppShellProvider>
  );
};

Styling Considerations

All renderer components insert iframes that fill their container. Ensure the container has appropriate dimensions:

/* Fullpage container */
.fullpage-container {
  width: 100%;
  height: 100vh;
}

/* Plugin container */
.plugin-container {
  width: 300px;
  height: 400px;
}

/* Modal container */
.modal-container {
  width: 100%;
  height: 100%;
}

Related

• Hooks - useAppShell hook

• Configuration - App registration

• API Reference - Complete type definitions