API Reference

This page provides a comprehensive overview of the main components and types exported by the @akinon/app-client library.

AppClientProvider

The AppClientProvider is a React component that provides the context for the app client functionality. It should be used to wrap the root component of your micro-frontend application.

Props

children: React.ReactNode
config: FullpageApplicationConfig | PluginApplicationConfig
eventBus?: Framebus

Context Value

The AppClientProvider provides the following context value:

data?: ApplicationData
params?: ApplicationParams
isLoading: boolean
invokeAction: <T = unknown>(actionKey: string, ...args: Array<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
locale: string
onLocaleChange: (callback: (newLocale: string) => void) => () => void
modalContext?: unknown

Usage


import { AppClientProvider } from '@akinon/app-client';
 
const App = () => (
  <AppClientProvider config={{ isDev: process.env.NODE_ENV === 'development' }}>
    {/* Your app components */}
  </AppClientProvider>
);

Types

AppClientContextState

This interface defines the shape of the context state provided by the AppClientProvider.


interface AppClientContextState {
  data?: ApplicationData;
  params?: ApplicationParams;
  isLoading: boolean;
  invokeAction: (
    actionKey: string,
    ...args: Array<unknown>
  ) => Promise<unknown>;
  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;
  locale: string;
  onLocaleChange: (callback: (newLocale: string) => void) => () => void;
  modalContext?: unknown;
}

FullpageApplicationConfig and PluginApplicationConfig

These types define the configuration options for fullpage and plugin applications, respectively. They extend the ApplicationConfig type with additional properties specific to each application type.


interface ApplicationConfig {
  isDev: boolean;
  forceRedirect?: boolean;
}
 
interface FullpageApplicationConfig extends ApplicationConfig {
  menu: Array<...>; // Define the menu structure
  navigation: {
    navigate: (payload: { path: string }) => void;
  };
}
 
 
interface PluginApplicationConfig extends ApplicationConfig {
  placeholderId: string | string[];
}

Note:

If you navigate with Application Navigation through a rich modal, application shell automatically navigates the parent client of the modal and closes the modal.

If you want to navigate within a rich modal without closing it, you should use your own navigation logic, e.g. React Router.

MultiAppProvider

MultiAppProvider enables the development of multiple client applications over a single URL.

Props

children: React.ReactNode
multiConfig: MultiAppConfig

Usage

Multiple Fullpage App


import { MultiAppProvider, type MultiAppConfig } from '@akinon/app-client';
 
export const multiConfig: MultiAppConfig = {
  apps: {
    firstApp: {
      basePath: "/first-app",
      type: "full_page",
      config: {
        isDev: true,
        forceRedirect: false,
        menu: [
          { path: "/...", label: '...' },
          { path: "/...", label: '...' },
          { path: "/...", label: '...' },
        ],
      },
    },
    secondApp: {
      basePath: "/second-app",
      type: "full_page",
      config: {
        isDev: true,
        forceRedirect: false,
        menu: [
          { path: "/...", label: '...' },
          { path: "/...", label: '...' },
          { path: "/...", label: '...' },
        ],
      },
    },
  },
  defaultApp: "firstApp",
};
 
const App = () => (
  <MultiAppProvider multiConfig={multiConfig}>
    {/* Your app components */}
  </MultiAppProvider>
);

Multiple Plugin App


import { MultiAppProvider, type MultiAppConfig } from '@akinon/app-client';
 
export const multiConfig: MultiAppConfig = {
  apps: {
    firstApp: {
      basePath: "/first-app",
      type: "plugin",
      config: {
        isDev: true,
        forceRedirect: true,
        placeholderId: "placeholder-1",
      },
    },
    secondApp: {
      basePath: "/second-app",
      type: "plugin",
      config: {
        isDev: true,
        forceRedirect: true,
        placeholderId: "placeholder-2",
      },
    },
  },
  defaultApp: "firstApp",
};
 
const App = () => (
  <MultiAppProvider multiConfig={multiConfig}>
    {/* Your app components */}
  </MultiAppProvider>
);

Types

MultiAppConfig

This interface, defines the shape of the multiConfig prop of the MultiAppProvider.


interface MultiAppConfig {
  apps: Record<string, AppConfig>;
  defaultApp?: string;
}
 
interface AppConfig {
  basePath: string;
  config: FullpageApplicationConfig | PluginApplicationConfig;
  type: RegisteredAppType;
}

For more detailed information on these types and their usage, refer to the source code and the specific documentation for each application type.