Usage

UI Protocol is Akinon's micro-frontend communication framework, enabling seamless data exchange and interaction between host applications and embedded micro-frontends.

What is UI Protocol?

UI Protocol provides a standardized way for micro-frontend applications to communicate with their host (shell) applications. Built on the postMessage API, it handles:

• Data Sharing - Pass data from shell to client applications

• Actions - Trigger shell-side operations from client applications

• Navigation - Coordinate routing between applications

• UI Helpers - Display modals, toasts, and other UI elements

Architecture

┌───────────────────────────────────────────────────────────┐
│                    Shell Application                      │
│                  (Omnitron, Seller Center)                │
│  ┌─────────────────────────────────────────────────────┐  │
│  │                  AppShellProvider                   │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │  │
│  │  │   Client    │  │   Client    │  │   Client    │  │  │
│  │  │  (iframe)   │  │  (iframe)   │  │  (iframe)   │  │  │
│  │  │             │  │             │  │             │  │  │
│  │  │ AppClient   │  │ AppClient   │  │ AppClient   │  │  │
│  │  │  Provider   │  │  Provider   │  │  Provider   │  │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘  │  │
│  └─────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────┘

Shell Application

The shell (or host) is the main application that embeds micro-frontends. It uses @akinon/app-shell to:

• Register and manage micro-frontend applications

• Share data with embedded clients

• Define actions that clients can invoke

• Handle navigation requests

Examples: Omnitron, Seller Center

Client Application

A client is a micro-frontend embedded within a shell via iframe. It uses @akinon/app-client to:

• Receive shared data from the shell

• Invoke shell-defined actions

• Request navigation changes

• Display UI elements (modals, toasts)

Examples: Marketplace Dashboard, AI Powered Search, custom plugins

Application Types

Fullpage Applications

Fullpage applications occupy the entire content area within the shell. They function as complete user interfaces with their own routing and state management.

┌──────────────────────────────────────┐
│  Shell (Header, Sidebar)             │
│  ┌────────────────────────────────┐  │
│  │                                │  │
│  │     Fullpage Client App        │  │
│  │        (entire area)           │  │
│  │                                │  │
│  └────────────────────────────────┘  │
└──────────────────────────────────────┘

Plugin Applications

Plugin applications are smaller widgets embedded in specific sections of a page. Multiple plugins can coexist on the same page.

┌──────────────────────────────────────┐
│  Shell Page                          │
│  ┌──────────┐  ┌──────────────────┐  │
│  │ Plugin A │  │   Shell Content  │  │
│  └──────────┘  │                  │  │
│  ┌──────────┐  │                  │  │
│  │ Plugin B │  │                  │  │
│  └──────────┘  └──────────────────┘  │
└──────────────────────────────────────┘

Prerequisites

Requirement	Version
Node.js	Hydrogen or higher
React	18.2.0 or higher

Installation

Choose the library based on your application type:

For Shell Applications

pnpm add @akinon/app-shell

For Client Applications

We recommend using the CLI to scaffold client applications. See the CLI documentation for details.

pnpm create akinon-app

Or install manually:

pnpm add @akinon/app-client

Communication Flow

1. Shell initializes with shared data, actions, and navigation config

2. Client loads inside an iframe and connects to the shell

3. Shell broadcasts data to all connected clients

4. Client requests actions or navigation changes

5. Shell executes the request and optionally responds

Shell                              Client
  │                                   │
  │◄──────── Client connects ─────────│
  │                                   │
  │────────── Share data ────────────►│
  │                                   │
  │◄─────── Request action ───────────│
  │                                   │
  │──────── Execute & respond ───────►│
  │                                   │

Benefits

• Modularity - Develop and deploy micro-frontends independently

• Consistency - Standardized communication patterns across all applications

• Security - Isolated iframes with controlled message passing

• Scalability - Easy to add new micro-frontends without modifying the shell

• Developer Experience - Type-safe APIs with React hooks

Next Steps

• Quick Start - Create your first client application

• ACC Integration - Deploy your application in Akinon Commerce Cloud

• Shell Application - Build a shell application

• Client Application - Build a client application