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

# Examples

This section provides complete working examples for different UI Protocol application types.

Each example demonstrates the recommended project structure and patterns using TanStack Router with file-based routing.

### <mark style="color:red;">Fullpage Application</mark>

A fullpage application takes over the entire content area of the shell and has its own menu.

#### Project Structure

```
src/
├── components/
│   └── Loading.tsx
├── hooks/
│   ├── index.tsx
│   └── useConfig.tsx
├── routes/
│   ├── __root.tsx
│   ├── index.tsx
│   └── about.tsx
├── AppWrapper.tsx
├── config.ts
├── main.tsx
├── providers.tsx
└── routeTree.gen.ts
```

#### Entry Point (main.tsx)

```tsx
import ReactDOM from 'react-dom/client';
import { RouterProvider, createRouter } from '@tanstack/react-router';
import '@akinon/fonts-jost-variable';
import '@akinon/ui-utils';

import { routeTree } from './routeTree.gen';

import './main.scss';

const router = createRouter({ routeTree });

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router;
  }
}

ReactDOM.createRoot(document.getElementById('root')!).render(
  <RouterProvider router={router} />
);
```

#### Root Route (routes/\_\_root.tsx)

```tsx
import { Outlet, createRootRoute } from '@tanstack/react-router';
import { Suspense } from 'react';

import { Providers } from '@/providers';
import { Loading } from '@/components/Loading';
import { AppWrapper } from '@/AppWrapper';

export const Route = createRootRoute({
  component: () => (
    <Suspense fallback={<Loading />}>
      <Providers>
        <AppWrapper>
          <Outlet />
        </AppWrapper>
      </Providers>
    </Suspense>
  ),
});
```

#### Home Route (routes/index.tsx)

```tsx
import { createFileRoute } from '@tanstack/react-router';
import { Layout, PageHeading, PageContent } from '@akinon/ui-layout';
import { Breadcrumb } from '@akinon/ui-breadcrumb';
import { useTranslation } from '@akinon/akilocale/react';

export const Route = createFileRoute('/')({
  component: PageHome,
});

function PageHome() {
  const { t } = useTranslation();

  return (
    <Layout>
      <Breadcrumb items={[{ title: t('home.page') }]} />
      <Layout.Content>
        <div className="page-heading-container">
          <PageHeading title={t('home.page')} />
        </div>
        <div className="page-content-container">
          <PageContent>{t('hello.world')}</PageContent>
        </div>
      </Layout.Content>
    </Layout>
  );
}
```

#### About Route (routes/about.tsx)

```tsx
import { createFileRoute } from '@tanstack/react-router';
import { Layout, PageHeading, PageContent } from '@akinon/ui-layout';
import { Breadcrumb } from '@akinon/ui-breadcrumb';
import { useTranslation } from '@akinon/akilocale/react';

export const Route = createFileRoute('/about')({
  component: PageAbout,
});

function PageAbout() {
  const { t } = useTranslation();

  return (
    <Layout>
      <Breadcrumb items={[{ title: t('about.page') }]} />
      <Layout.Content>
        <div className="page-heading-container">
          <PageHeading title={t('about.page')} />
        </div>
        <div className="page-content-container">
          <PageContent>{t('about.content')}</PageContent>
        </div>
      </Layout.Content>
    </Layout>
  );
}
```

#### Providers (providers.tsx)

```tsx
import { AppClientProvider } from '@akinon/app-client';
import { AkinonUiProvider } from '@akinon/ui-system';
import { useRouter } from '@tanstack/react-router';

import { config as rootConfig } from '@/config';

export const Providers = ({ children }: { children: React.ReactNode }) => {
  const router = useRouter();

  const config = {
    ...rootConfig,
    navigation: {
      navigate: ({ path }: { path: string }) => {
        router.navigate({ to: path });
      },
    },
  };

  return (
    <AkinonUiProvider>
      <AppClientProvider config={config}>
        {children}
      </AppClientProvider>
    </AkinonUiProvider>
  );
};
```

#### Configuration (config.ts)

```typescript
import type { FullpageApplicationConfig } from '@akinon/app-client';
import { i18n } from '@akinon/akilocale/react';

const { t } = i18n;

export const config: Omit<FullpageApplicationConfig, 'navigation'> = {
  isDev: true,
  forceRedirect: true,
  menu: [
    {
      label: t('home.page'),
      path: '/',
    },
    {
      label: t('about.page'),
      path: '/about',
    },
  ],
};
```

#### App Wrapper (AppWrapper.tsx)

Handles locale synchronization with the shell:

```tsx
import { useEffect } from 'react';
import { useAppClient } from '@akinon/app-client';
import { useTranslation } from '@akinon/akilocale/react';
import { akidate } from '@akinon/akidate';

export const AppWrapper = ({
  children,
}: {
  children: React.ReactNode;
}) => {
  const { i18n } = useTranslation();
  const { locale, onLocaleChange } = useAppClient();

  useEffect(() => {
    i18n.changeLanguage(locale);
    akidate.setLocale(locale);

    const unsubscribe = onLocaleChange((newLocale) => {
      i18n.changeLanguage(newLocale);
      akidate.setLocale(newLocale);
    });

    return unsubscribe;
  }, [locale, onLocaleChange, i18n]);

  return children;
};
```

***

### <mark style="color:red;">Plugin Application</mark>

A plugin application embeds into specific areas of the shell using placeholder IDs. Plugin applications don't need routing since they render a single component.

#### Project Structure

```
src/
├── components/
│   ├── Content.tsx
│   └── Loading.tsx
├── App.tsx
├── AppWrapper.tsx
├── config.ts
├── main.tsx
└── providers.tsx
```

#### Entry Point (main.tsx)

```tsx
import ReactDOM from 'react-dom/client';
import '@akinon/fonts-jost-variable';
import '@akinon/ui-utils';

import { App } from '@/App';

import './main.scss';

ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
```

#### Configuration (config.ts)

```typescript
import type { PluginApplicationConfig } from '@akinon/app-client';

export const config: PluginApplicationConfig = {
  isDev: true,
  forceRedirect: true,
  placeholderId: 'product-widget',
};
```

#### Providers (providers.tsx)

```tsx
import { AppClientProvider } from '@akinon/app-client';
import { AkinonUiProvider } from '@akinon/ui-system';

import { config } from '@/config';

export const Providers = ({ children }: { children: React.ReactNode }) => {
  return (
    <AkinonUiProvider>
      <AppClientProvider config={config}>
        {children}
      </AppClientProvider>
    </AkinonUiProvider>
  );
};
```

#### App Component (App.tsx)

```tsx
import { Suspense } from 'react';

import { Providers } from '@/providers';
import { Loading } from '@/components/Loading';
import { Content } from '@/components/Content';
import { AppWrapper } from '@/AppWrapper';

export const App = () => {
  return (
    <Suspense fallback={<Loading />}>
      <Providers>
        <AppWrapper>
          <Content />
        </AppWrapper>
      </Providers>
    </Suspense>
  );
};
```

#### Content Component (components/Content.tsx)

```tsx
import { useAppClient } from '@akinon/app-client';
import { useTranslation } from '@akinon/akilocale/react';

export const Content = () => {
  const { t } = useTranslation();
  const { params, showToast } = useAppClient();

  const handleClick = () => {
    showToast(t('action.success'), 'success');
  };

  return (
    <div>
      <h3>{t('plugin.title')}</h3>
      <p>Product ID: {params?.productId}</p>
      <button onClick={handleClick}>{t('action.button')}</button>
    </div>
  );
};
```

***

### <mark style="color:red;">Multi-Hybrid Application</mark>

A multi-hybrid application serves both fullpage and plugin applications from a single codebase using different base paths.

#### Project Structure

```
src/
├── components/
├── routes/
│   ├── __root.tsx
│   ├── fullpage-app/
│   │   ├── route.tsx
│   │   └── home.tsx
│   └── plugin-app/
│       └── route.tsx
├── AppWrapper.tsx
├── main.tsx
├── providers.tsx
└── routeTree.gen.ts
```

#### Entry Point (main.tsx)

```tsx
import ReactDOM from 'react-dom/client';
import { RouterProvider, createRouter } from '@tanstack/react-router';
import { MultiAppProvider } from '@akinon/app-client';
import '@akinon/fonts-jost-variable';
import '@akinon/ui-utils';

import { routeTree } from './routeTree.gen';
import { useConfig } from '@/hooks';

import './main.scss';

const router = createRouter({ routeTree });

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router;
  }
}

const Main = () => {
  const { config } = useConfig();

  return (
    <MultiAppProvider multiConfig={config}>
      <RouterProvider router={router} />
    </MultiAppProvider>
  );
};

ReactDOM.createRoot(document.getElementById('root')!).render(<Main />);
```

#### Root Route (routes/\_\_root.tsx)

```tsx
import { Outlet, createRootRoute } from '@tanstack/react-router';
import { Suspense } from 'react';

import { Providers } from '@/providers';
import { Loading } from '@/components/Loading';
import { AppWrapper } from '@/AppWrapper';

export const Route = createRootRoute({
  component: () => (
    <Suspense fallback={<Loading />}>
      <Providers>
        <AppWrapper>
          <Outlet />
        </AppWrapper>
      </Providers>
    </Suspense>
  ),
});
```

#### Fullpage App Layout (routes/fullpage-app/route.tsx)

```tsx
import { Outlet, createFileRoute } from '@tanstack/react-router';

export const Route = createFileRoute('/fullpage-app')({
  component: () => <Outlet />,
});
```

#### Fullpage Home (routes/fullpage-app/home.tsx)

```tsx
import { createFileRoute } from '@tanstack/react-router';
import { Layout, PageHeading, PageContent } from '@akinon/ui-layout';
import { Breadcrumb } from '@akinon/ui-breadcrumb';
import { useTranslation } from '@akinon/akilocale/react';

export const Route = createFileRoute('/fullpage-app/home')({
  component: PageFullpageApp,
});

function PageFullpageApp() {
  const { t } = useTranslation();

  return (
    <Layout>
      <Breadcrumb
        items={[
          { title: t('fullpage.app.in.multi.hybrid') },
          { title: t('home.page') },
        ]}
      />
      <Layout.Content>
        <div className="page-heading-container">
          <PageHeading title={t('fullpage.app.in.multi.hybrid')} />
        </div>
        <div className="page-content-container">
          <PageContent>{t('hello.world')}</PageContent>
        </div>
      </Layout.Content>
    </Layout>
  );
}
```

#### Plugin App Route (routes/plugin-app/route.tsx)

```tsx
import { createFileRoute } from '@tanstack/react-router';
import { Layout, PageHeading, PageContent } from '@akinon/ui-layout';
import { useTranslation } from '@akinon/akilocale/react';

export const Route = createFileRoute('/plugin-app')({
  component: PagePluginApp,
});

function PagePluginApp() {
  const { t } = useTranslation();

  return (
    <Layout>
      <Layout.Content>
        <div className="page-heading-container">
          <PageHeading title={t('plugin.app.in.multi.hybrid')} />
        </div>
        <div className="page-content-container">
          <PageContent>{t('hello.world')}</PageContent>
        </div>
      </Layout.Content>
    </Layout>
  );
}
```

#### Config Hook (hooks/useConfig.tsx)

```tsx
import { useTranslation } from '@akinon/akilocale/react';
import type { MultiAppConfig } from '@akinon/app-client';
import { useRef } from 'react';

export const useConfig = () => {
  const { t } = useTranslation();

  const configRef = useRef<MultiAppConfig>({
    apps: {
      fullpageApp: {
        basePath: '/fullpage-app',
        type: 'full_page',
        config: {
          isDev: true,
          forceRedirect: false,
          menu: [
            {
              label: t('home.page'),
              path: '/home',
            },
          ],
        },
      },
      pluginApp: {
        basePath: '/plugin-app',
        type: 'plugin',
        config: {
          isDev: true,
          forceRedirect: true,
          placeholderId: 'plugin-placeholder',
        },
      },
    },
    defaultApp: 'fullpageApp',
  });

  return { config: configRef.current };
};
```

#### Providers (providers.tsx)

```tsx
import { AkinonUiProvider } from '@akinon/ui-system';

export const Providers = ({ children }: { children: React.ReactNode }) => {
  return <AkinonUiProvider>{children}</AkinonUiProvider>;
};
```

***

### <mark style="color:red;">Common Patterns</mark>

#### Data Access Pattern

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

const DataConsumer = () => {
  const { data, isLoading } = useAppClient();

  if (isLoading) {
    return <Skeleton />;
  }

  return (
    <div>
      <p>User: {data?.user?.name}</p>
      <p>Theme: {data?.theme}</p>
    </div>
  );
};
```

#### Action Invocation Pattern

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

const ActionHandler = () => {
  const { invokeAction, showToast, showErrorMessage } = useAppClient();

  const handleSubmit = async (formData: FormData) => {
    try {
      const result = await invokeAction('submitForm', formData);
      showToast('Form submitted successfully!', 'success');
      return result;
    } catch (error) {
      showErrorMessage('Submission Failed', error.message);
    }
  };

  return <Form onSubmit={handleSubmit} />;
};
```

#### Navigation Pattern

```tsx
import { useAppClient } from '@akinon/app-client';
import { useState } from 'react';

const NavigationComponent = () => {
  const { navigate, showConfirmationDialog } = useAppClient();
  const [hasUnsavedChanges, setHasUnsavedChanges] = useState(false);

  const handleNavigate = (path: string) => {
    if (hasUnsavedChanges) {
      showConfirmationDialog({
        title: 'Unsaved Changes',
        content: 'You have unsaved changes. Leave anyway?',
        onConfirm: () => navigate({ path }),
        onCancel: () => {},
      });
    } else {
      navigate({ path });
    }
  };

  return (
    <nav>
      <button onClick={() => handleNavigate('/dashboard')}>Dashboard</button>
      <button onClick={() => handleNavigate('/settings')}>Settings</button>
    </nav>
  );
};
```

#### Rich Modal Pattern

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

// Parent component
const ProductList = () => {
  const { showRichModal } = useAppClient();

  const openDetail = (productId: string) => {
    showRichModal(
      `/product-detail`,
      { productId, mode: 'view' },
      { maxWidth: 800, maxHeight: '90vh' }
    );
  };

  return (
    <ul>
      {products.map(product => (
        <li key={product.id}>
          {product.name}
          <button onClick={() => openDetail(product.id)}>View</button>
        </li>
      ))}
    </ul>
  );
};

// Modal content (separate route)
const ProductDetail = () => {
  const { modalContext } = useAppClient();
  const { productId, mode } = modalContext as { productId: string; mode: string };

  return (
    <div>
      <h1>Product Detail</h1>
      <p>ID: {productId}</p>
      <p>Mode: {mode}</p>
    </div>
  );
};
```

### <mark style="color:red;">Getting Started</mark>

Use the CLI to create a new application:

```bash
pnpm create akinon-app
```

Select your application type when prompted:

* **full\_page** - Fullpage application
* **plugin** - Plugin application
* **multi\_full\_page** - Multiple fullpage applications
* **multi\_plugin** - Multiple plugin applications

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

* Quick Start - Getting started guide
* Shell Application - Shell documentation
* Client Application - Client documentation


---

# 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/examples.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.
