# Introduction

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. 

### <mark style="color:red;">What is a Client Application?</mark>

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

### <mark style="color:red;">Key Features</mark>

* 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

### <mark style="color:red;">Installation</mark>

```bash
pnpm add @akinon/app-client
```

### <mark style="color:red;">Basic Usage</mark>

Wrap your application with `AppClientProvider`:

```tsx
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>
);
```

### <mark style="color:red;">How It Works</mark>

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](https://github.com/braintree/framebus) library
5. **Ongoing communication** for actions, navigation, and data updates

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

### <mark style="color:red;">Client Can Also Be a Shell</mark>

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.

```tsx
// 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>
);
```

### <mark style="color:red;">Next Steps</mark>

* Configuration - Configure fullpage and plugin applications
* Hooks - Using useAppClient hook
* i18n - Internationalization in client apps
* API Reference - Complete API documentation


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.akinon.com/akinon-ui/ui-protocol/client-application/introduction.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.