Quick Start

Create and run your first UI Protocol client application in under 5 minutes.

Create a New Application

Use the CLI to scaffold a new client application:

pnpm create akinon-app my-app

The CLI will prompt you for:

Prompt	Description
Project name	Application identifier (e.g., my-app)
Project type	fullpage, plugin, multi_fullpage, or multi_plugin
Package manager	pnpm, npm, or yarn
Install dependencies	Whether to install packages immediately

Start Development Server

Navigate to your project and start the development server:

cd my-app
pnpm dev

Your application is now running at http://localhost:4001.

Test with Shell Server

To test your application within a simulated shell environment:

pnpm dev:shell

This starts a mock shell at http://localhost:4000 that:

• Provides a realistic shell interface (header, sidebar)

• Simulates data sharing from shell to client

• Enables testing of actions and navigation

Project Structure

The generated application follows this structure:

my-app/
├── src/
│   ├── pages/           # Page components
│   ├── components/      # Reusable UI components
│   ├── hooks/           # Custom React hooks
│   ├── providers.tsx    # Context providers
│   ├── routes.tsx       # Routing configuration
│   ├── config.ts        # App configuration
│   └── main.tsx         # Entry point
├── public/              # Static assets and locales
├── __tests__/           # Test files
└── shell.config.js      # Shell server configuration

Using App Client

Access shell data and functionality using the useAppClient hook:

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

const MyPage = () => {
  const { data, navigate, invokeAction } = useAppClient();

  // Access shared data from shell
  const user = data?.user;

  // Navigate within the shell
  const goToProducts = () => {
    navigate({ path: '/products' });
  };

  // Invoke a shell-defined action
  const showNotification = () => {
    invokeAction('showToast', { message: 'Hello from client!' });
  };

  return (
    <div>
      <h1>Welcome, {user?.name}</h1>
      <button onClick={goToProducts}>Go to Products</button>
      <button onClick={showNotification}>Show Toast</button>
    </div>
  );
};

Using UI Components

Import components from @akinon/ui-* packages:

import { Button } from '@akinon/ui-button';
import { Card } from '@akinon/ui-card';
import { Input } from '@akinon/ui-input';

const MyForm = () => {
  return (
    <Card title="Create Product">
      <Input placeholder="Product name" />
      <Button type="primary">Save</Button>
    </Card>
  );
};

Test in Production Shell

Use the Chrome Extension to test your local app within a production shell:

First, download the UI Protocol Chrome Extension:

9KB

ui-protocol-chrome-extension.zip

archive

Open

1. Load as unpacked extension in Chrome (chrome://extensions)

2. Configure the extension:

   • Web URL: http://localhost:4001

   • App Name: Your app's display name

   • App Type: full_page or plugin

3. Navigate to the production shell (e.g., Omnitron)

4. Your local app renders inside the real shell

Build for Production

Create an optimized production build:

pnpm build

Output is generated in the dist/ directory, ready for ACC deployment.

Next Steps

• ACC Integration - Register your app in ACC

• Client Application - Deep dive into client development

• Shell Application - Build a shell application