API Reference

Components

AppClientProvider

The root provider component that enables communication with the shell application.

import { AppClientProvider } from '@akinon/app-client';

Props

Property	Type	Required	Default	Description
children	ReactNode	Yes	-	Child components
config	FullpageApplicationConfig | PluginApplicationConfig	Yes	-	Application configuration
eventBus	Framebus	No	undefined	Custom framebus instance (for testing)

Usage

<AppClientProvider config={{ isDev: true }}>
  <App />
</AppClientProvider>

---

MultiAppProvider

Enables multiple client applications to be served from a single URL with different base paths.

import { MultiAppProvider } from '@akinon/app-client';

Props

Property	Type	Required	Description
children	ReactNode	Yes	Child components
multiConfig	MultiAppConfig	Yes	Configuration for multiple apps

Usage

const multiConfig: MultiAppConfig = {
  apps: {
    firstApp: {
      basePath: '/first-app',
      type: 'full_page',
      config: {
        isDev: true,
        menu: [{ path: '/dashboard', label: 'Dashboard' }]
      }
    },
    secondApp: {
      basePath: '/second-app',
      type: 'full_page',
      config: {
        isDev: true,
        menu: [{ path: '/settings', label: 'Settings' }]
      }
    }
  },
  defaultApp: 'firstApp'
};

<MultiAppProvider multiConfig={multiConfig}>
  <App />
</MultiAppProvider>

---

Hooks

useAppClient

Access the client context for communicating with the shell.

import { useAppClient } from '@akinon/app-client';

const { data, navigate, showToast, invokeAction } = useAppClient();

Return Value: AppClientContextState

Property	Type	Description
data	ApplicationData | undefined	Shared data from shell
params	ApplicationParams | undefined	Plugin parameters
isLoading	boolean	Data loading state
modalContext	unknown	Rich modal context data
locale	string	Current locale
navigate	(payload: ShellNavigationPayload) => void	Request shell navigation
invokeAction	<T>(key: string, ...args: unknown[]) => Promise<T>	Invoke custom action
showModalDialog	(options: ModalDialogOptions) => boolean	Show modal dialog
showConfirmationDialog	(options: ConfirmDialogOptions) => boolean	Show confirmation
showToast	(content: string, type: ToastType) => boolean	Show toast
showErrorMessage	(title: string, content: string) => boolean	Show error
showRichModal	(path, context?, size?, closeIconColor?) => boolean	Show rich modal
removeSearchParams	(keys: string | string[]) => void	Remove URL params
setSearchParams	(params: Record<string, string | number>) => void	Set URL params
onLocaleChange	(callback: (locale: string) => void) => () => void	Subscribe to locale changes

---

Types

AppClientContextState

The context state provided by AppClientProvider.

interface AppClientContextState {
  data?: ApplicationData;
  params?: ApplicationParams;
  isLoading: boolean;
  invokeAction: <T = unknown>(actionKey: string, ...args: unknown[]) => Promise<T>;
  navigate: (payload: ShellNavigationPayload) => void;
  showModalDialog?: (options: {
    title: string;
    content: string;
    onConfirm?: () => void;
    onCancel?: () => void;
  }) => boolean;
  showConfirmationDialog?: (options: {
    title: string;
    content: string;
    onConfirm?: (data: unknown) => void;
    onCancel?: () => void;
  }) => boolean;
  showToast?: (
    content: string,
    type: 'success' | 'warning' | 'error' | 'loading' | 'destroy'
  ) => boolean;
  showErrorMessage?: (title: string, content: string) => boolean;
  showRichModal?: (
    path: string,
    context?: unknown,
    size?: ApplicationModalSize,
    closeIconColor?: string
  ) => boolean;
  removeSearchParams?: (keys: string | string[]) => void;
  setSearchParams?: (searchParams: Record<string, string | number>) => void;
  locale: string;
  onLocaleChange: (callback: (newLocale: string) => void) => () => void;
  modalContext?: unknown;
}

---

FullpageApplicationConfig

Configuration for fullpage applications.

interface FullpageApplicationConfig extends ApplicationConfig {
  menu: Page[];
  navigation?: ApplicationNavigation;
}

interface Page {
  path: string;
  label: string | { [language: string]: string };
}

interface ApplicationNavigation {
  navigate: (payload: { path: string }) => void;
}

---

PluginApplicationConfig

Configuration for plugin applications.

interface PluginApplicationConfig extends ApplicationConfig {
  placeholderId: string | string[];
}

---

ApplicationConfig

Base configuration interface.

interface ApplicationConfig {
  isDev?: boolean;
  forceRedirect?: boolean;
}

---

ShellNavigationPayload

Payload for navigation requests.

interface ShellNavigationPayload {
  path: string;
  external?: boolean;
}

---

ApplicationData

Shared data from the shell.

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

---

ApplicationParams

Parameters for plugin applications.

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

---

ApplicationModalSize

Modal size configuration.

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

---

MultiAppConfig

Configuration for multiple applications.

interface MultiAppConfig {
  apps: Record<string, AppConfig>;
  defaultApp?: string;
}

interface AppConfig {
  basePath: string;
  type: 'full_page' | 'plugin';
  config: FullpageApplicationConfig | PluginApplicationConfig;
}

---

Events

AppClient listens for and emits the following events:

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
SET_PARAMS	Shell → Client	Shell sends plugin parameters
INVOKE_ACTION	Client → Shell	Client invokes custom action
INVOKE_DEFAULT_ACTION	Client → Shell	Client invokes default action
NAVIGATE	Client → Shell	Client requests navigation
NAVIGATE_CHILD	Shell → Client	Shell triggers client navigation
ACTION_CONFIRMED	Shell → Client	Shell confirms an action
ACTION_CANCELED	Shell → Client	Shell cancels an action
LOCALE_CHANGED	Shell → Client	Shell notifies locale change
SET_HEIGHT	Client → Shell	Client sends iframe height

Notes

If you navigate using navigate() from within a rich modal, the shell automatically navigates the parent client and closes the modal. To navigate within a rich modal without closing it, use your own navigation logic (e.g., React Router).

Related

• Introduction - Getting started with AppClient

• Hooks - Using the useAppClient hook

• Configuration - Application configuration