# Quick Start

### <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](/tutorials/acc/how-to-move-apps-into-acc.md).

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

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


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.