Introduction

AppShell is the core library for building shell (host) applications in the UI Protocol ecosystem.

Introduction

It manages the integration of micro-frontend applications, handling data sharing, user actions, navigation, and communication.

What is a Shell Application?

A shell application is the host that embeds and manages micro-frontend clients. Examples include Omnitron and Seller Center. The shell provides:

• Layout and Navigation - Header, sidebar, and routing

• Shared Data - User info, permissions, configuration

• Actions - Functions that clients can invoke

• Communication Channel - Message passing via postMessage API

Key Responsibilities

Data Management

• Share data with all connected micro-frontends

• Synchronize state changes across applications

• Maintain data isolation between different clients

User Actions

• Define actions that clients can invoke (e.g., show toast, open modal)

• Process action requests and return results

• Handle built-in actions (navigation, UI helpers)

Navigation

• Manage routing for fullpage applications

• Handle navigation requests from clients

• Coordinate URL and query parameter changes

Application Lifecycle

• Register and configure micro-frontend applications

• Load/unload clients via iframes

• Manage communication channels per client

Installation

pnpm add @akinon/app-shell

Basic Setup

Wrap your application with AppShellProvider:

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

const App = () => {
  return (
    <AppShellProvider
      apps={registeredApps}
      navigation={navigationConfig}
      data={sharedData}
      actions={shellActions}
    >
      {/* Your shell application */}
    </AppShellProvider>
  );
};

Provider Props

Prop	Type	Required	Description
apps	RegisteredApp[]	Yes	List of registered micro-frontend applications
navigation	ShellNavigation	Yes	Navigation helper functions
data	ApplicationData	No	Shared data available to all clients
actions	ApplicationActions	No	Custom actions that clients can invoke

Registered Apps

The apps prop contains the list of micro-frontend applications that can be rendered:

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

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

How It Works

1. Shell initializes with AppShellProvider and registered apps

2. Client iframe loads and sends SET_CONFIG event

3. Shell responds with SET_DATA and SET_APP_ID

4. Communication established via framebus library

5. Ongoing communication for actions, navigation, and data updates

┌─────────────────────────────────────────┐
│            AppShellProvider             │
│  ┌───────────────────────────────────┐  │
│  │          Shell Content            │  │
│  │  ┌─────────────────────────────┐  │  │
│  │  │   AppRenderer (fullpage)    │  │  │
│  │  │   or PluginRenderer         │  │  │
│  │  │   ┌─────────────────────┐   │  │  │
│  │  │   │   Client iframe     │   │  │  │
│  │  │   │   (micro-frontend)  │   │  │  │
│  │  │   └─────────────────────┘   │  │  │
│  │  └─────────────────────────────┘  │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

Next Steps

• Configuration - Configure data sharing, actions, and navigation

• Hooks - Shell-side React hooks

• Components - AppRenderer, PluginRenderer, ModalRenderer

• API Reference - Complete API documentation