useAppShell

The primary hook for accessing the shell context. It provides access to registered apps, configurations, navigation, and iframe references.

import { useAppShell } from '@akinon/app-shell';

const ShellComponent = () => {
  const { apps, configs, navigate } = useAppShell();

  return (
    <div>
      <h1>Registered Apps: {apps.length}</h1>
      <button onClick={() => navigate({ path: '/dashboard' })}>
        Go to Dashboard
      </button>
    </div>
  );
};

Return Value

The useAppShell hook returns an AppShellContextState object:

Property	Type	Description
apps	RegisteredApp[]	List of registered micro-frontend applications
configs	Map<number | UUID, ApplicationConfig>	Configuration for each registered app
navigate	(payload: NavigationPayload) => void	Navigation function
frames	MutableRefObject<Map<number | UUID, HTMLIFrameElement>>	References to iframe elements
buses	MutableRefObject<Map<number | UUID, Framebus>>	Framebus instances for communication
instances	Map<number | UUID, AppInstanceInfo>	App instances by ID
modals	Map<UUID, number | UUID>	UUID values for rich modals
modalContext	Map<UUID, unknown>	Context data for modals

AppShellContextState Type

interface AppShellContextState {
  apps: RegisteredApp[];
  configs: Map<number | UUID, PluginApplicationConfig | FullpageApplicationConfig>;
  navigate: (payload: ApplicationNavigationPayload) => void;
  frames?: React.MutableRefObject<Map<number | UUID, HTMLIFrameElement>>;
  buses?: React.MutableRefObject<Map<number | UUID, Framebus>>;
  instances: Map<number | UUID, AppInstanceInfo>;
  modals?: Map<UUID, number | UUID>;
  modalContext?: Map<UUID, unknown>;
}

interface AppInstanceInfo {
  id: number | UUID;
  basePath: string;
  config: FullpageApplicationConfig | PluginApplicationConfig;
  iframe: HTMLIFrameElement;
  bus: Framebus;
}

Usage Examples

Accessing Registered Apps

const AppList = () => {
  const { apps } = useAppShell();

  return (
    <ul>
      {apps.map(app => (
        <li key={app.pk}>
          {app.name} - {app.config.visible_type}
        </li>
      ))}
    </ul>
  );
};

Programmatic Navigation

const NavigationButtons = () => {
  const { navigate } = useAppShell();

  return (
    <div>
      <button onClick={() => navigate({ path: '/orders' })}>Orders</button>
      <button onClick={() => navigate({ path: '/products' })}>Products</button>
      <button onClick={() => navigate({ path: '/settings', id: 1 })}>
        Settings (App 1)
      </button>
    </div>
  );
};

Accessing App Configurations

const AppInfo = ({ appId }: { appId: number }) => {
  const { configs } = useAppShell();
  const config = configs.get(appId);

  if (!config) return <p>App not found</p>;

  return (
    <div>
      <p>URL: {config.web_url}</p>
      <p>Type: {config.visible_type}</p>
    </div>
  );
};

Working with Iframe References

const IframeManager = () => {
  const { frames } = useAppShell();

  const reloadApp = (appId: number) => {
    const iframe = frames?.current.get(appId);
    if (iframe) {
      iframe.contentWindow?.location.reload();
    }
  };

  return (
    <button onClick={() => reloadApp(1)}>
      Reload App 1
    </button>
  );
};

Sending Messages via Framebus

const MessageSender = () => {
  const { buses } = useAppShell();

  const sendMessage = (appId: number, event: string, data: any) => {
    const bus = buses?.current.get(appId);
    if (bus) {
      bus.emit(event, data);
    }
  };

  return (
    <button onClick={() => sendMessage(1, 'custom-event', { foo: 'bar' })}>
      Send Custom Message
    </button>
  );
};

Best Practices

1. Use at the Right Level

Call useAppShell in components that need shell context, not at the top level:

// ✅ Good - Use where needed
const AppRenderer = ({ id }) => {
  const { frames } = useAppShell();
  // ...
};

// ❌ Avoid - Don't destructure everything at top level
const App = () => {
  const shellContext = useAppShell(); // Then pass to children
};

2. Check for Optional Values

Some properties are optional and may be undefined:

const Component = () => {
  const { frames, buses } = useAppShell();

  const sendMessage = (appId: number) => {
    const bus = buses?.current.get(appId);
    if (!bus) {
      console.warn('Framebus not available for app:', appId);
      return;
    }
    bus.emit('event', data);
  };
};

3. Memoize Derived Values

When computing values from the context, memoize them:

const ActiveApps = () => {
  const { apps } = useAppShell();

  const activeApps = useMemo(
    () => apps.filter(app => app.is_active && app.is_visible),
    [apps]
  );

  return <AppList apps={activeApps} />;
};

Related

• Components - AppRenderer, PluginRenderer, ModalRenderer

• API Reference - Complete type definitions