Introduction

This library provides a React context and hooks for enabling inter-app communication, navigation, and other essential functionalities.

The @akinon/app-client library is a crucial part of the UI Protocol, designed to facilitate the creation of micro-frontend applications that seamlessly integrate with the main shell application.

What is a Client Application?

A client application is a micro-frontend that runs inside an iframe and communicates with the shell application. Examples include marketplace extensions, analytics widgets, and custom modules. The client:

• Receives Shared Data - Accesses user info, settings, and configuration from the shell

• Invokes Actions - Triggers shell functions like showing toasts or modals

• Requests Navigation - Asks the shell to navigate to different routes

• Sends Configuration - Tells the shell about its menu structure and capabilities

Key Features

• Seamless integration with the shell application

• Easy-to-use React hooks for accessing client functionalities

• Support for navigation between micro-frontend applications

• Ability to invoke custom actions defined in the shell

• Helper functions for displaying modals, toasts, and more

• TypeScript support for improved developer experience

Installation

pnpm add @akinon/app-client

Basic Usage

Wrap your application with AppClientProvider:

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

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

  const handleClick = () => {
    showToast('Action completed!', 'success');
    navigate({ path: '/dashboard' });
  };

  return (
    <div>
      <p>Welcome, {data?.user?.name}</p>
      <button onClick={handleClick}>Go to Dashboard</button>
    </div>
  );
};

const App = () => (
  <AppClientProvider config={{ isDev: process.env.NODE_ENV === 'development' }}>
    <MyComponent />
  </AppClientProvider>
);

How It Works

1. Client initializes with AppClientProvider and configuration

2. Client sends SET_CONFIG event to the shell with its configuration

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

┌─────────────────────────────────────────┐
│              Shell (iframe)             │
│  ┌───────────────────────────────────┐  │
│  │        AppClientProvider          │  │
│  │  ┌─────────────────────────────┐  │  │
│  │  │      Your Application       │  │  │
│  │  │                             │  │  │
│  │  │  useAppClient() → {         │  │  │
│  │  │    data,                    │  │  │
│  │  │    navigate,                │  │  │
│  │  │    showToast,               │  │  │
│  │  │    invokeAction,            │  │  │
│  │  │    ...                      │  │  │
│  │  │  }                          │  │  │
│  │  │                             │  │  │
│  │  └─────────────────────────────┘  │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

Client Can Also Be a Shell

A client application can also act as a shell for other micro-frontends. This enables nested hierarchies where a fullpage application hosts plugin applications within it.

// This app is a client to the main shell
// but also a shell for its own plugins
import { AppClientProvider } from '@akinon/app-client';
import { AppShellProvider, PluginRenderer } from '@akinon/app-shell';

const App = () => (
  <AppClientProvider config={clientConfig}>
    <AppShellProvider apps={pluginApps} {...shellProps}>
      <MainContent />
      <PluginRenderer placeholderId="sidebar-widget" />
    </AppShellProvider>
  </AppClientProvider>
);

Next Steps

• Configuration - Configure fullpage and plugin applications

• Hooks - Using useAppClient hook

• i18n - Internationalization in client apps

• API Reference - Complete API documentation