> 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/quick-start.md).

# Quick Start

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

### <mark style="color:red;">Create a New Application</mark>

Use the CLI to scaffold a new client application:

```bash
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                   |

### <mark style="color:red;">Start Development Server</mark>

Navigate to your project and start the development server:

```bash
cd my-app
pnpm dev
```

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

### <mark style="color:red;">Test with Shell Server</mark>

To test your application within a simulated shell environment:

```bash
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

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

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
```

### <mark style="color:red;">Using App Client</mark>

Access shell data and functionality using the `useAppClient` hook:

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

### <mark style="color:red;">Using UI Components</mark>

Import components from `@akinon/ui-*` packages:

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

### <mark style="color:red;">Test in Production Shell</mark>

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

First, download the UI Protocol Chrome Extension:

{% file src="/files/9m1JxsBpO8gqHESQ0lho" %}

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

### <mark style="color:red;">Build for Production</mark>

Create an optimized production build:

```bash
pnpm build
```

Output is generated in the `dist/` directory, ready for [ACC deployment](https://docs.akinon.com/tutorials/acc/how-to-move-apps-into-acc.md).

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

* [ACC Integration](https://docs.akinon.com/akinon-ui/ui-protocol/acc-integration.md) - Register your app in ACC
* [Client Application](https://docs.akinon.com/akinon-ui/ui-protocol/client-application.md) - Deep dive into client development
* [Shell Application](https://docs.akinon.com/akinon-ui/ui-protocol/shell-application.md) - Build a shell application


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.akinon.com/akinon-ui/ui-protocol/quick-start.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
