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
basePath?: string — the base path this application is served under. It is prefixed onto every path handed to resolveShellUrl, so a link resolves to the same destination navigate reaches. MultiAppProvider gives each app its own basePath along with a bus opened on the matching channel; a standalone AppClientProvider accepts the prop as well, but the bus it opens for itself carries no base path, so pass basePath only together with an eventBus opened on the channel the shell registered the app under.

Warning: if you pass an eventBus opened on a base-pathed channel but no basePath, nothing fails: navigate still reaches the right place, because the shell applies the base path itself, while resolveShellUrl returns a url without it. The button works and the link beside it goes to the wrong page. With config.isDev set, the provider logs a warning when it receives a shellBaseUrl in that state.

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 — pass newTab: true to have the shell host open the destination in a new browser tab
shellBaseUrl?: string
resolveShellUrl: (path: string) => string
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

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;
  shellBaseUrl?: string;
  resolveShellUrl: (path: string) => string;
  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;
  removeSearchParams?: (keys: string | string[]) => void;
  setSearchParams?: (searchParams: Record<string, string | number>) => void;
}

ShellNavigationPayload

The payload accepted by navigate. newTab is forwarded to the shell host untouched; the client itself never calls window.open, because only the host knows its own url grammar.


interface ShellNavigationPayload {
  id?: number | UUID;
  path: string;
  external?: boolean;
  newTab?: boolean;
}

ApplicationData

The shared data broadcast by the shell. Besides whatever the host application puts there, the shell adds shellBaseUrl — its own absolute base url, resolved for this app. The key is absent until that first emit arrives, and absent for good when the host implements no ShellNavigation.resolveUrl; the shell never falls back to the page origin. The client additionally ignores a reported value that is not an http(s) url on the shell’s own origin.


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

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.