Actions

The AppShell library enables seamless interaction between the shell and its micro-frontends through a robust action system.

Overview

Actions are mechanisms through which clients can request the shell to perform certain operations, such as displaying messages, navigating between pages, or invoking custom logic.

Action Types

AppShell supports two types of actions:

1. Default Actions - Predefined UI operations (toast, modal, confirmation dialog)

2. Custom Actions - Application-specific operations defined by the shell

Default Actions

Default actions are predefined operations that ensure a consistent user experience across micro-frontends. These actions cover common functionalities that clients frequently need.

Available Default Actions

Action	Parameters	Description
showModalDialog	(title, content)	Display a modal dialog with title and content
showConfirmationDialog	(title, content)	Show a confirmation dialog, returns boolean
showToast	(content, type)	Show a brief toast notification
showErrorMessage	(title, content)	Display an error message prominently
showRichModal	(uuid, path, context?, size?, closeIconColor?)	Open a rich modal with iframe content
removeSearchParams	(keys)	Remove specified URL search parameters
setSearchParams	(searchParams)	Set or update URL search parameters

Implementing Default Actions

const defaultActions = {
  showModalDialog: (title: string, content: string) => {
    Modal.info({ title, content });
  },

  showConfirmationDialog: (title: string, content: string): boolean => {
    return window.confirm(`${title}\n${content}`);
  },

  showToast: (content: string, type: 'success' | 'warning' | 'error' | 'loading' | 'destroy') => {
    if (type === 'destroy') {
      message.destroy();
    } else {
      message[type](content);
    }
  },

  showErrorMessage: (title: string, content: string) => {
    Modal.error({ title, content });
  },

  showRichModal: (uuid: string, path: string, context?: unknown) => {
    // Open a modal with iframe content
    openRichModal({ uuid, path, context });
  },

  removeSearchParams: (keys: string[]) => {
    const params = new URLSearchParams(window.location.search);
    keys.forEach(key => params.delete(key));
    window.history.replaceState({}, '', `?${params.toString()}`);
  },

  setSearchParams: (searchParams: Record<string, string | number>) => {
    const params = new URLSearchParams(window.location.search);
    Object.entries(searchParams).forEach(([key, value]) => {
      params.set(key, String(value));
    });
    window.history.replaceState({}, '', `?${params.toString()}`);
  }
};

Custom Actions

Beyond default actions, you can define custom actions specific to your application. These are operations that micro-frontends can invoke to interact with the shell.

Defining Custom Actions

const customActions = {
  performLogout: () => {
    authService.logout();
    window.location.href = '/login';
  },

  fetchUserData: async (userId: number) => {
    const response = await api.get(`/users/${userId}`);
    return response.data;
  },

  openProductDetail: (productId: string) => {
    navigate(`/products/${productId}`);
  },

  refreshPermissions: async () => {
    const permissions = await api.get('/permissions');
    updatePermissions(permissions.data);
  }
};

Combining Actions

Pass both default and custom actions to AppShellProvider:

import { AppShellProvider, type ApplicationActions } from '@akinon/app-shell';

const App = () => {
  const actions: ApplicationActions = {
    // Default actions
    showModalDialog: (title, content) => Modal.info({ title, content }),
    showConfirmationDialog: (title, content) => window.confirm(`${title}\n${content}`),
    showToast: (content, type) => message[type](content),
    showErrorMessage: (title, content) => Modal.error({ title, content }),
    showRichModal: (uuid, path, context) => openRichModal({ uuid, path, context }),
    removeSearchParams: (keys) => { /* ... */ },
    setSearchParams: (params) => { /* ... */ },
    
    // Custom actions
    actions: {
      performLogout: () => authService.logout(),
      fetchUserData: async (userId) => api.get(`/users/${userId}`),
      refreshPermissions: async () => { /* ... */ }
    }
  };

  return (
    <AppShellProvider
      apps={registeredApps}
      navigation={navigationConfig}
      data={sharedData}
      actions={actions}
    >
      {/* Your shell application */}
    </AppShellProvider>
  );
};

ApplicationActions Type

interface ApplicationActions {
  // Default actions
  showModalDialog?: (title: string, content: string) => void;
  showConfirmationDialog?: (title: string, content: string) => boolean;
  showToast?: (
    content: string,
    type: 'success' | 'warning' | 'error' | 'loading' | 'destroy'
  ) => void;
  showErrorMessage?: (title: string, content: string) => void;
  showRichModal?: (
    uuid: string,
    path: string,
    context?: unknown,
    size?: ApplicationModalSize,
    closeIconColor?: string
  ) => void;
  removeSearchParams?: (keys: string[]) => void;
  setSearchParams?: (searchParams: Record<string, string | number>) => void;
  
  // Custom actions
  actions: {
    [key: string]: (...args: any[]) => any;
  };
}

type ApplicationModalSize = 'small' | 'medium' | 'large' | 'full';

Invoking Actions (Client Side)

Clients invoke actions via the useAppClient hook:

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

const ClientComponent = () => {
  const { actions } = useAppClient();

  const handleSave = async () => {
    try {
      await saveData();
      actions.showToast('Saved successfully!', 'success');
    } catch (error) {
      actions.showErrorMessage('Save Failed', error.message);
    }
  };

  const handleLogout = () => {
    actions.actions.performLogout();
  };

  return (
    <div>
      <button onClick={handleSave}>Save</button>
      <button onClick={handleLogout}>Logout</button>
    </div>
  );
};

For detailed information about using actions on the client side, see the Client Application documentation.

Async Actions

Actions can be asynchronous. The client will await the result:

// Shell
const actions: ApplicationActions = {
  actions: {
    validateOrder: async (orderId: string) => {
      const result = await orderService.validate(orderId);
      return result; // This will be returned to the client
    }
  }
};

// Client
const { actions } = useAppClient();
const isValid = await actions.actions.validateOrder('order-123');

Best Practices

1. Keep Actions Simple

Actions should perform a single, well-defined operation.

// ❌ Bad - Action does too much
actions: {
  doEverything: async () => {
    await fetchData();
    await updateUI();
    await sendAnalytics();
    await notifyUser();
  }
}

// ✅ Good - Separate, focused actions
actions: {
  fetchData: async () => { /* ... */ },
  sendAnalytics: (event) => { /* ... */ },
  showNotification: (message) => { /* ... */ }
}

2. Return Values When Needed

If clients need a result, make sure to return it:

actions: {
  // Returns a boolean
  confirmDelete: async (itemId) => {
    const confirmed = await showConfirmDialog('Delete this item?');
    if (confirmed) {
      await deleteItem(itemId);
    }
    return confirmed;
  }
}

3. Handle Errors Gracefully

Catch and handle errors within actions:

actions: {
  saveData: async (data) => {
    try {
      await api.save(data);
      return { success: true };
    } catch (error) {
      console.error('Save failed:', error);
      return { success: false, error: error.message };
    }
  }
}

Next Steps

• Navigation - Configure navigation helpers

• Data Sharing - Share data with clients