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.

Fullpage Application

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)

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)

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)

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)

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)

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)

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:

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;
};

---

Plugin Application

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)

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)

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

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

Providers (providers.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)

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)

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

---

Multi-Hybrid Application

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)

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)

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)

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

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

Fullpage Home (routes/fullpage-app/home.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)

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)

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)

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

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

---

Common Patterns

Data Access Pattern

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

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

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

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

Getting Started

Use the CLI to create a new application:

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

Related

• Quick Start - Getting started guide

• Shell Application - Shell documentation

• Client Application - Client documentation