API Reference

Complete API reference for the @akinon/app-shell package, including components, hooks, and type definitions.

Components

AppShellProvider

The root provider component that manages micro-frontend communication and state.

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

Props

Property	Type	Required	Default	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	-	Actions that clients can invoke

---

AppRenderer

Renders fullpage micro-frontend applications.

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

Props

Property	Type	Required	Default	Description
id	number	Yes	-	Unique identifier for the application
path	string	No	-	Path to append to the iframe src URL

---

PluginRenderer

Renders plugin micro-frontend applications in designated placeholders.

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

Props

Property	Type	Required	Default	Description
placeholderId	string	Yes	-	ID of the placeholder where plugin renders
params	ApplicationParams	No	-	Parameters to pass to the plugin

---

ModalRenderer

Renders micro-frontend content within a modal.

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

Props

Property	Type	Required	Default	Description
uuid	UUID	Yes	-	Unique identifier for the modal
path	string	Yes	-	Path to render within the modal
size	ApplicationModalSize	No	-	Size configuration

---

Hooks

useAppShell

Access the shell context for managing micro-frontend interactions.

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

const { apps, configs, navigate, frames, buses } = useAppShell();

Return Value: AppShellContextState

Property	Type	Description
apps	RegisteredApp[]	List of registered applications
configs	Map<number | UUID, ApplicationConfig>	Configuration per app
navigate	(payload: NavigationPayload) => void	Navigation function
frames	MutableRefObject<Map<number | UUID, HTMLIFrameElement>>	Iframe references
buses	MutableRefObject<Map<number | UUID, Framebus>>	Framebus instances
instances	Map<number | UUID, AppInstanceInfo>	App instances
modals	Map<UUID, number | UUID>	Modal UUID mappings
modalContext	Map<UUID, unknown>	Modal context data

---

Types

RegisteredApp

Describes a registered micro-frontend application.

interface RegisteredApp {
  pk: number;
  name?: string;
  config: {
    web_url: string;
    visible_type: 'full_page' | 'plugin';
    placeholder?: string;
  };
  is_visible: boolean;
  is_active: boolean;
}

---

ShellNavigation

Navigation helper interface.

interface ShellNavigation {
  navigate: (payload: NavigationPayload) => void;
}

interface NavigationPayload {
  path: string;
  id?: number;
}

---

ApplicationData

Shared data structure.

interface ApplicationData {
  searchParams?: Record<string, string>;
  [key: string]: any;
}

---

ApplicationActions

Actions that clients can invoke.

interface ApplicationActions {
  // Default actions
  showModalDialog?: (title: string, content: string) => void;
  showConfirmationDialog?: (title: string, content: string) => boolean;
  showToast?: (
    content: string,
    type: 'success' | 'warning' | 'error' | 'loading' | 'destroy'
  ) => void;
  showErrorMessage?: (title: string, content: string) => void;
  showRichModal?: (
    uuid: UUID,
    path: string,
    context?: unknown,
    size?: ApplicationModalSize,
    closeIconColor?: string
  ) => void;
  removeSearchParams?: (keys: string[]) => void;
  setSearchParams?: (searchParams: Record<string, string | number>) => void;
  
  // Custom actions
  actions: {
    [key: string]: (...args: any[]) => any;
  };
}

---

ApplicationModalSize

Modal size configuration.

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

---

ApplicationParams

Parameters for plugin applications.

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

---

AppShellContextState

Context state returned by useAppShell.

interface AppShellContextState {
  apps: RegisteredApp[];
  configs: Map<number | UUID, PluginApplicationConfig | FullpageApplicationConfig>;
  navigate: (payload: NavigationPayload) => void;
  frames?: React.MutableRefObject<Map<number | UUID, HTMLIFrameElement>>;
  buses?: React.MutableRefObject<Map<number | UUID, Framebus>>;
  instances: Map<number | UUID, AppInstanceInfo>;
  modals?: Map<UUID, number | UUID>;
  modalContext?: Map<UUID, unknown>;
}

---

AppInstanceInfo

Information about an app instance.

interface AppInstanceInfo {
  id: number | UUID;
  basePath: string;
  config: FullpageApplicationConfig | PluginApplicationConfig;
  iframe: HTMLIFrameElement;
  bus: Framebus;
}

---

FullpageApplicationConfig

Configuration for fullpage applications.

interface FullpageApplicationConfig {
  web_url: string;
  visible_type: 'full_page';
}

---

PluginApplicationConfig

Configuration for plugin applications.

interface PluginApplicationConfig {
  web_url: string;
  visible_type: 'plugin';
  placeholder: string;
}

---

Events

AppShell uses the following events for communication (defined in @akinon/app-shared):

Event	Direction	Description
SET_CONFIG	Client → Shell	Client sends its configuration
SET_DATA	Shell → Client	Shell sends shared data
SET_APP_ID	Shell → Client	Shell sends app identifier
SET_MODAL_CONTEXT	Shell → Client	Shell sends modal context data
SET_HEIGHT	Client → Shell	Client sends its iframe height
SET_PARAMS	Shell → Client	Shell sends plugin parameters
INVOKE_ACTION	Client → Shell	Client invokes a custom action
INVOKE_DEFAULT_ACTION	Client → Shell	Client invokes a default action
NAVIGATE	Client → Shell	Client requests navigation
NAVIGATE_CHILD	Shell → Client	Shell triggers navigation on child app
ACTION_CONFIRMED	Shell → Client	Shell confirms an action (triggers onConfirm)
ACTION_CANCELED	Shell → Client	Shell cancels an action (triggers onCancel)
LOCALE_CHANGED	Shell → Client	Shell notifies locale change

Related

• Introduction - Getting started with AppShell

• Hooks - Using the useAppShell hook

• Components - Renderer components