useAppClient

This hook provides access to the client context, including shared data, actions, navigation, and more.

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

const MyComponent = () => {
  const { data, navigate, showToast } = useAppClient();

  return (
    <div>
      <p>User: {data?.user?.name}</p>
      <button onClick={() => navigate({ path: '/home' })}>Home</button>
      <button onClick={() => showToast('Hello!', 'success')}>Greet</button>
    </div>
  );
};

Return Value

The useAppClient hook returns an AppClientContextState object:

Property	Type	Description
data	ApplicationData | undefined	Shared data from the shell
params	ApplicationParams | undefined	Parameters passed to plugin applications
isLoading	boolean	Whether the application data is loading
modalContext	unknown	Context data for rich modals
locale	string	Current locale from the shell
navigate	(payload) => void	Navigate within the shell
invokeAction	(key, ...args) => Promise	Invoke custom shell actions
showModalDialog	(options) => boolean	Show a modal dialog
showConfirmationDialog	(options) => boolean	Show a confirmation dialog
showToast	(content, type) => boolean	Show a toast notification
showErrorMessage	(title, content) => boolean	Show an error message
showRichModal	(path, context?, size?, closeIconColor?) => boolean	Show a rich modal
removeSearchParams	(keys) => void	Remove URL search params
setSearchParams	(params) => void	Set URL search params
onLocaleChange	(callback) => () => void	Subscribe to locale changes

Accessing Shared Data

The data property contains the shared data from the shell:

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

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

  return (
    <div>
      <h1>Welcome, {data?.user?.name}</h1>
      <p>Theme: {data?.theme}</p>
      <p>Language: {data?.locale}</p>
    </div>
  );
};

Navigation

Request the shell to navigate to a different route:

const NavigationExample = () => {
  const { navigate } = useAppClient();

  return (
    <div>
      <button onClick={() => navigate({ path: '/orders' })}>
        View Orders
      </button>
      <button onClick={() => navigate({ path: '/products?category=electronics' })}>
        Electronics
      </button>
    </div>
  );
};

Invoking Custom Actions

Call custom actions defined in the shell:

const ActionExample = () => {
  const { invokeAction } = useAppClient();

  const handleLogout = async () => {
    try {
      await invokeAction('performLogout');
    } catch (error) {
      console.error('Logout failed:', error);
    }
  };

  const handleFetchData = async () => {
    const result = await invokeAction('fetchUserData', userId);
    console.log('User data:', result);
  };

  return (
    <div>
      <button onClick={handleLogout}>Logout</button>
      <button onClick={handleFetchData}>Fetch Data</button>
    </div>
  );
};

Default Actions

showToast

Display a brief notification:

const ToastExample = () => {
  const { showToast } = useAppClient();

  return (
    <div>
      <button onClick={() => showToast('Saved successfully!', 'success')}>
        Success
      </button>
      <button onClick={() => showToast('Something went wrong', 'error')}>
        Error
      </button>
      <button onClick={() => showToast('Please wait...', 'loading')}>
        Loading
      </button>
      <button onClick={() => showToast('', 'destroy')}>
        Clear All
      </button>
    </div>
  );
};

showConfirmationDialog

Display a confirmation dialog with callbacks:

const ConfirmExample = () => {
  const { showConfirmationDialog } = useAppClient();

  const handleDelete = () => {
    showConfirmationDialog({
      title: 'Delete Item',
      content: 'Are you sure you want to delete this item?',
      onConfirm: () => {
        console.log('User confirmed deletion');
        deleteItem();
      },
      onCancel: () => {
        console.log('User cancelled');
      }
    });
  };

  return <button onClick={handleDelete}>Delete</button>;
};

showErrorMessage

Display an error message dialog:

const ErrorExample = () => {
  const { showErrorMessage } = useAppClient();

  const handleError = (error: Error) => {
    showErrorMessage('Operation Failed', error.message);
  };

  return <button onClick={() => handleError(new Error('Test'))}>Show Error</button>;
};

showRichModal

Open a rich modal with another micro-frontend:

const RichModalExample = () => {
  const { showRichModal } = useAppClient();

  const openProductDetail = (productId: string) => {
    showRichModal(
      `/products/${productId}`,           // path
      { productId, mode: 'view' },        // context
      { maxWidth: 800, maxHeight: '90vh' }, // size
      '#ffffff'                            // closeIconColor
    );
  };

  return (
    <button onClick={() => openProductDetail('prod-123')}>
      View Product
    </button>
  );
};

URL Search Params

Manage URL search parameters:

const SearchParamsExample = () => {
  const { setSearchParams, removeSearchParams, data } = useAppClient();

  const applyFilters = () => {
    setSearchParams({
      category: 'electronics',
      page: 1,
      limit: 20
    });
  };

  const clearFilters = () => {
    removeSearchParams(['category', 'page', 'limit']);
  };

  return (
    <div>
      <p>Current params: {JSON.stringify(data?.searchParams)}</p>
      <button onClick={applyFilters}>Apply Filters</button>
      <button onClick={clearFilters}>Clear Filters</button>
    </div>
  );
};

Plugin Parameters

Access parameters passed to plugin applications:

// Shell passes params via PluginRenderer
// <PluginRenderer placeholderId="product-widget" params={{ productId: '123' }} />

const PluginComponent = () => {
  const { params } = useAppClient();

  return (
    <div>
      <p>Product ID: {params?.productId}</p>
    </div>
  );
};

Modal Context

Access context data in rich modals:

// When opened via showRichModal(path, context)
const ModalContent = () => {
  const { modalContext } = useAppClient();

  return (
    <div>
      <h1>Product Detail</h1>
      <p>ID: {(modalContext as any)?.productId}</p>
      <p>Mode: {(modalContext as any)?.mode}</p>
    </div>
  );
};

Locale Handling

React to locale changes from the shell:

import { useEffect } from 'react';
import { i18n } from '@akinon/akilocale/react';

const LocaleAwareComponent = () => {
  const { locale, onLocaleChange } = useAppClient();

  useEffect(() => {
    // Set initial locale
    i18n.changeLanguage(locale);

    // Subscribe to changes
    const unsubscribe = onLocaleChange((newLocale) => {
      i18n.changeLanguage(newLocale);
    });

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

  return <div>Current locale: {locale}</div>;
};

Best Practices

1. Handle Loading State

Always check isLoading before accessing data:

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

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

  return <Content data={data} />;
};

2. Optional Chaining for Data

Use optional chaining when accessing nested data:

// ✅ Good
const userName = data?.user?.name;

// ❌ Bad - may throw
const userName = data.user.name;

3. Error Handling for Actions

Wrap action invocations in try-catch:

const handleAction = async () => {
  try {
    const result = await invokeAction('someAction', arg1, arg2);
    showToast('Success!', 'success');
  } catch (error) {
    showErrorMessage('Error', error.message);
  }
};

Next Steps

• Configuration - Configure your client application
• i18n - Internationalization
• API Reference - Complete API documentation