> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/akinon-ui/ui-protocol/shell-application/introduction.md).

# Introduction

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

It manages the integration of micro-frontend applications, handling data sharing, user actions, navigation, and communication.

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

A shell application is the host that embeds and manages micro-frontend clients. Examples include Omnitron and Seller Center. The shell provides:

* **Layout and Navigation** - Header, sidebar, and routing
* **Shared Data** - User info, permissions, configuration
* **Actions** - Functions that clients can invoke
* **Communication Channel** - Message passing via postMessage API

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

#### Data Management

* Share data with all connected micro-frontends
* Synchronize state changes across applications
* Maintain data isolation between different clients

#### User Actions

* Define actions that clients can invoke (e.g., show toast, open modal)
* Process action requests and return results
* Handle built-in actions (navigation, UI helpers)

#### Navigation

* Manage routing for fullpage applications
* Handle navigation requests from clients
* Coordinate URL and query parameter changes

#### Application Lifecycle

* Register and configure micro-frontend applications
* Load/unload clients via iframes
* Manage communication channels per client

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

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

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

Wrap your application with `AppShellProvider`:

```tsx
import { AppShellProvider } from '@akinon/app-shell';

const App = () => {
  return (
    <AppShellProvider
      apps={registeredApps}
      navigation={navigationConfig}
      data={sharedData}
      actions={shellActions}
    >
      {/* Your shell application */}
    </AppShellProvider>
  );
};
```

#### Provider Props

| Prop         | Type                 | Required | Description                                    |
| ------------ | -------------------- | -------- | ---------------------------------------------- |
| `apps`       | `RegisteredApp[]`    | Yes      | List of registered micro-frontend applications |
| `navigation` | `ShellNavigation`    | Yes      | Navigation helper functions                    |
| `data`       | `ApplicationData`    | No       | Shared data available to all clients           |
| `actions`    | `ApplicationActions` | No       | Custom actions that clients can invoke         |

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

The `apps` prop contains the list of micro-frontend applications that can be rendered:

```tsx
import type { RegisteredApp } from '@akinon/app-shell';

const registeredApps: RegisteredApp[] = [
  {
    pk: 1,
    name: 'Marketplace Dashboard',
    config: {
      web_url: 'https://marketplace.example.com',
      visible_type: 'full_page'
    },
    is_visible: true,
    is_active: true
  },
  {
    pk: 2,
    name: 'Analytics Widget',
    config: {
      web_url: 'https://analytics.example.com',
      visible_type: 'plugin',
      placeholder: 'dashboard-sidebar'
    },
    is_visible: true,
    is_active: true
  }
];
```

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

1. **Shell initializes** with `AppShellProvider` and registered apps
2. **Client iframe loads** and sends `SET_CONFIG` event
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

```
┌─────────────────────────────────────────┐
│            AppShellProvider             │
│  ┌───────────────────────────────────┐  │
│  │          Shell Content            │  │
│  │  ┌─────────────────────────────┐  │  │
│  │  │   AppRenderer (fullpage)    │  │  │
│  │  │   or PluginRenderer         │  │  │
│  │  │   ┌─────────────────────┐   │  │  │
│  │  │   │   Client iframe     │   │  │  │
│  │  │   │   (micro-frontend)  │   │  │  │
│  │  │   └─────────────────────┘   │  │  │
│  │  └─────────────────────────────┘  │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘
```

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

* [Configuration](/akinon-ui/ui-protocol/shell-application/configuration.md) - Configure data sharing, actions, and navigation
* [Hooks](/akinon-ui/ui-protocol/shell-application/useappshell.md) - Shell-side React hooks
* [Components](/akinon-ui/ui-protocol/shell-application/components.md) - AppRenderer, PluginRenderer, ModalRenderer
* [API Reference](/akinon-ui/ui-protocol/shell-application/api-reference.md) - Complete API documentation


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.