Navigation

This allows micro-frontends to redirect users to different routes managed by the shell without direct access to the shell's router.

Client applications can request navigation within the shell application.

How It Works

1. Client calls navigate({ path: '/target-path' })

2. Request is sent to shell via framebus

3. Shell executes navigation using its router

4. URL changes and appropriate content is rendered

Basic Usage

Use the navigate function from useAppClient:

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

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

  return (
    <div>
      <button onClick={() => navigate({ path: '/dashboard' })}>
        Dashboard
      </button>
      <button onClick={() => navigate({ path: '/orders' })}>
        Orders
      </button>
      <button onClick={() => navigate({ path: '/settings' })}>
        Settings
      </button>
    </div>
  );
};

Navigation Payload

interface ShellNavigationPayload {
  path: string;
  external?: boolean;
}

Property	Type	Description
path	string	Target path to navigate to (should start with /)
external	boolean	If true, navigates at shell level instead of extension level

Understanding external:

• external: false (default) → Navigates within extension scope Example: /dashboard → shell.com/en/en-us/extension/1/dashboard

• external: true → Navigates at shell level Example: /dashboard → shell.com/en/en-us/dashboard

Navigation Examples

Simple Navigation

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

  return (
    <nav>
      <a onClick={() => navigate({ path: '/' })}>Home</a>
      <a onClick={() => navigate({ path: '/products' })}>Products</a>
      <a onClick={() => navigate({ path: '/about' })}>About</a>
    </nav>
  );
};

With Query Parameters

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

  const goToFilteredProducts = (category: string) => {
    navigate({ path: `/products?category=${category}&page=1` });
  };

  return (
    <div>
      <button onClick={() => goToFilteredProducts('electronics')}>
        Electronics
      </button>
      <button onClick={() => goToFilteredProducts('clothing')}>
        Clothing
      </button>
    </div>
  );
};

Dynamic Routes

const OrderList = ({ orders }) => {
  const { navigate } = useAppClient();

  const viewOrder = (orderId: string) => {
    navigate({ path: `/orders/${orderId}` });
  };

  return (
    <ul>
      {orders.map(order => (
        <li key={order.id}>
          Order #{order.id}
          <button onClick={() => viewOrder(order.id)}>View</button>
        </li>
      ))}
    </ul>
  );
};

Shell-Level Navigation

Navigate to shell routes (outside extension scope):

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

  const goToShellDashboard = () => {
    navigate({ 
      path: '/dashboard',
      external: true 
    });
  };

  return (
    <button onClick={goToShellDashboard}>
      Go to Main Dashboard
    </button>
  );
};

Navigation from Rich Modals

When you call navigate() from within a rich modal, the shell automatically:

1. Navigates the parent client

2. Closes the modal

To navigate within a rich modal without closing it, use your own routing logic (e.g., React Router).

// Navigation that CLOSES the modal
const ModalContent = () => {
  const { navigate } = useAppClient();

  const goToDetails = () => {
    navigate({ path: '/details' }); // Modal closes, shell navigates
  };

  return <button onClick={goToDetails}>Go to Details</button>;
};

// Navigation WITHIN the modal (stays open)
import { useNavigate } from 'react-router';

const ModalContentWithInternalNav = () => {
  const routerNavigate = useNavigate();

  const goToStep2 = () => {
    routerNavigate('/modal-step-2'); // Modal stays open
  };

  return <button onClick={goToStep2}>Next Step</button>;
};

Client-Side Navigation

For fullpage applications, you can also configure internal navigation:

import { useNavigate } from 'react-router';
import { AppClientProvider, type FullpageApplicationConfig } from '@akinon/app-client';

const App = () => {
  const routerNavigate = useNavigate();

  const config: FullpageApplicationConfig = {
    isDev: true,
    menu: [
      { path: '/dashboard', label: 'Dashboard' },
      { path: '/orders', label: 'Orders' }
    ],
    navigation: {
      navigate: ({ path }) => routerNavigate(path)
    }
  };

  return (
    <AppClientProvider config={config}>
      <AppContent />
    </AppClientProvider>
  );
};

When the shell triggers NAVIGATE_CHILD event, your navigation.navigate function is called.

Programmatic Navigation Patterns

After Form Submission

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

  const handleSubmit = async (data: OrderData) => {
    try {
      const order = await createOrder(data);
      showToast('Order created!', 'success');
      navigate({ path: `/orders/${order.id}` });
    } catch (error) {
      showToast('Failed to create order', 'error');
    }
  };

  return <OrderForm onSubmit={handleSubmit} />;
};

Conditional Navigation

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

  const handleClick = () => {
    if (data?.user?.role === 'admin') {
      navigate({ path: '/admin/settings' });
    } else {
      navigate({ path: '/access-denied' });
    }
  };

  return <button onClick={handleClick}>Admin Settings</button>;
};

Navigation with Confirmation

const UnsavedChangesGuard = () => {
  const { navigate, showConfirmationDialog } = useAppClient();
  const [hasChanges, setHasChanges] = useState(false);

  const handleNavigate = (path: string) => {
    if (hasChanges) {
      showConfirmationDialog({
        title: 'Unsaved Changes',
        content: 'You have unsaved changes. Are you sure you want to leave?',
        onConfirm: () => navigate({ path }),
        onCancel: () => {}
      });
    } else {
      navigate({ path });
    }
  };

  return (
    <button onClick={() => handleNavigate('/dashboard')}>
      Go to Dashboard
    </button>
  );
};

Best Practices

1. Use Meaningful Paths

// ✅ Good - descriptive paths
navigate({ path: '/orders/123/details' });
navigate({ path: '/products?category=electronics' });

// ❌ Bad - unclear paths
navigate({ path: '/p/123' });
navigate({ path: '/page1' });

2. Handle Navigation Errors

const SafeNavigation = () => {
  const { navigate, showErrorMessage } = useAppClient();

  const safeNavigate = (path: string) => {
    try {
      navigate({ path });
    } catch (error) {
      showErrorMessage('Navigation Error', 'Unable to navigate');
    }
  };
};

3. Avoid Navigation on Mount

Don't navigate immediately on component mount - let the user interact first:

// ❌ Bad - navigates immediately
useEffect(() => {
  navigate({ path: '/somewhere' });
}, []);

// ✅ Good - navigation triggered by user action
const handleClick = () => {
  navigate({ path: '/somewhere' });
};

Next Steps

• Actions - Invoke shell actions

• Hooks - Complete useAppClient reference