Skip to Content
UI ProtocolGetting StartedClient App Development

Client App Development

This guide provides comprehensive instructions for developing client applications using the UI Protocol system.

Overview

Client applications are React-based applications that integrate with larger host applications such as Omnitron or Seller Center. These applications can function as complete page implementations or as embedded components within predefined placeholders.

Getting Started

Create Your Application

Use the create-akinon-app tool to initialize a new project:

npx create-akinon-app my-app
# or
yarn create akinon-app my-app
# or
pnpm create akinon-app my-app

Alternatively, you can install the CLI globally:

npm install -g @akinon/ui-cli
create-akinon-app my-app

Configure Your Application

The creation process will prompt you for several configuration options:

The CLI will prompt for the following information:

  • Project name: The application identifier
  • Project type: Application architecture type
  • Package manager: Dependency management tool (pnpm, npm, or yarn)
  • Install dependencies: Whether to install packages immediately

Application Types

Select the appropriate application type based on your requirements:

Fullpage Application

Complete page implementations that handle entire user interface screens. Suitable for:

  • Dashboard interfaces
  • Administrative panels
  • Settings and configuration pages
  • Standalone application screens

Plugin Application

Component-based applications that render within predefined placeholders in host applications. Appropriate for:

  • Data visualization components
  • Interactive widgets
  • Form components
  • Content display modules

Plugin applications cannot modify shell application navigation or sidebar elements. They operate within designated content areas only.

Multi Applications

Single repositories that contain multiple related applications:

  • Multi-Fullpage: Multiple fullpage applications in one codebase for related functionality
  • Multi-Plugin: Multiple plugin applications organized as a component library

Multi applications are designed for organizing related functionality in a single repository, not for A/B testing purposes.

Initialize Development Environment

Navigate to the application directory and start the development server:

cd my-app
npm run dev

The application will be available at http://localhost:4001.

Development Environment

Development Server

The development server provides hot module replacement for efficient development. Code changes are reflected immediately without manual page refresh.

Shell Server Integration

Execute the shell server to test application integration:

npm run dev:shell

The shell server launches at http://localhost:4000 and provides a mock host environment that simulates production integration scenarios. This environment includes:

  • Realistic application shell interface
  • Sample navigation structure
  • Mock data providers
  • Integration testing capabilities

Project Architecture

The generated application follows a structured organization:

my-app/
├── src/
│   ├── pages/           # Page components and routing
│   ├── components/      # Reusable UI components
│   ├── hooks/          # Custom React hooks
│   ├── providers.tsx   # Context providers and state management
│   ├── routes.tsx      # Application routing configuration
│   ├── config.ts       # Application configuration
│   └── main.tsx        # Application entry point
├── public/             # Static assets and localization files
├── __tests__/          # Test specifications
└── shell.config.js     # Shell server configuration

Key Configuration Files

src/providers.tsx: Contains React Context providers for state management, theming, and internationalization. This file establishes the application’s data flow and global state structure.

src/routes.tsx: Defines application routing using React Router. Configure navigation paths, route parameters, and nested routing structures here.

src/config.ts: Application-specific configuration including API endpoints, feature flags, and environment-specific settings.

UI Components and Design System

Applications are pre-configured with the Akinon UI Kit, providing a comprehensive component library and design system.

Component Library

The UI Kit includes production-ready React components:

  • Form controls (buttons, inputs, selectors)
  • Layout utilities (grids, containers, spacing)
  • Data presentation (tables, cards, typography)
  • User feedback (alerts, loading indicators, notifications)

Installation and Usage

Install additional UI component packages as needed:

npm install @akinon/ui-button @akinon/ui-card @akinon/ui-layout
# or
yarn add @akinon/ui-button @akinon/ui-card @akinon/ui-layout
# or
pnpm add @akinon/ui-button @akinon/ui-card @akinon/ui-layout

Import and use components in your application:

import { Button } from '@akinon/ui-button';
import { Card } from '@akinon/ui-card';
import { Layout } from '@akinon/ui-layout';
 
function MyComponent() {
  return (
    <Layout>
      <Card>
        <h2>Application Content</h2>
        <Button variant="primary">Action Button</Button>
      </Card>
    </Layout>
  );
}

Documentation and Resources

  • Component Documentation: UI Kit Overview
  • Interactive Examples: Storybook 
  • Design Specifications: Design tokens and theming guidelines

Production Integration Testing

Chrome Extension Integration

For testing applications within production host environments, use the UI Protocol Chrome Extension:

  1. Download: UI Protocol Chrome Extension
  2. Install: Load as unpacked extension in Chrome Developer Mode
  3. Configure: Set local development server endpoint
  4. Test: Navigate to host application to see integrated results

The extension intercepts application configuration API calls and redirects them to your local development environment. This enables:

  • Production environment testing
  • Real data integration validation
  • User workflow testing
  • Integration debugging

Extension Configuration

Configure the extension with the following parameters:

  • Web URL: Local development server URL (e.g., http://localhost:4001)
  • App Name: Application display identifier
  • App Type: Application type matching your implementation

Application Development

Feature Implementation

Applications provide structured templates for common development tasks:

  • Routing Configuration: Modify src/routes.tsx for navigation setup
  • State Management: Implement providers in src/providers.tsx
  • API Integration: Utilize app-client utilities for data fetching
  • Styling: Apply global styles in src/main.scss

Production Build

Generate production-ready builds:

npm run build

This command produces optimized static assets in the dist/ directory suitable for CDN deployment.

Host Application Integration

To integrate with host applications:

  1. Deploy built application to accessible URL
  2. Register application in host application configuration
  3. App Shell handles loading and rendering automatically

Additional Resources

ACC IntegrationIntroduction